# Build a LangGraph Agent with the Redpanda AI Gateway

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [labs-full.txt](https://docs.redpanda.com/labs-full.txt)

---
title: Build a LangGraph Agent with the Redpanda AI Gateway
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-connect-version: 4.93.0
latest-redpanda-tag: v26.1.9
docname: langchain-agent
page-component-name: labs
page-version: master
page-component-version: master
page-component-title: Labs
page-relative-src-path: langchain-agent.adoc
page-edit-url: https://github.com/redpanda-data/redpanda-labs/edit/main/docs/modules/ai-agents/pages/langchain-agent.adoc
description: Build a ReAct agent using LangGraph that connects to the Redpanda AI Gateway for unified LLM access and MCP tool calling.
page-topic-type: lab
learning-objective-1: Build and run a LangGraph ReAct agent that connects to the Redpanda AI Gateway
learning-objective-2: Authenticate with the AI Gateway using the OIDC client_credentials flow
learning-objective-3: Configure LangGraph to route LLM requests through the AI Gateway's OpenAI-compatible interface
page-git-created-date: "2026-03-06"
page-git-modified-date: "2026-03-06"
---

<!-- Source: https://docs.redpanda.com/labs/ai-agents/langchain-agent.md -->

Build a Python agent using [LangGraph](https://langchain-ai.github.io/langgraph/) that connects to the Redpanda AI Gateway for unified LLM access and MCP tool calling, with optional [LangSmith](https://www.langchain.com/langsmith) tracing.

After completing this lab, you will be able to:

-   Build and run a LangGraph ReAct agent that connects to the Redpanda AI Gateway

-   Authenticate with the AI Gateway using the OIDC client\_credentials flow

-   Configure LangGraph to route LLM requests through the AI Gateway’s OpenAI-compatible interface


## [](#what-youll-explore)What you’ll explore

-   **AI Gateway as a unified LLM interface**: The gateway provides an OpenAI-compatible API that routes to any upstream model provider (such as Google Gemini), handling provider-specific authentication and request translation.

-   **OIDC authentication**: Authenticate with the gateway using a Redpanda Cloud service account and the OAuth 2.0 `client_credentials` grant.

-   **Dynamic MCP tool discovery**: Use the gateway’s MCP endpoint to discover and call tools at runtime, without hard-coding tool definitions.


## [](#prerequisites)Prerequisites

-   Python 3.12 or later

-   [Poetry](https://python-poetry.org/) for dependency management

-   A Redpanda Cloud account with:

    -   A cluster that has the AI Gateway enabled

    -   A service account with permissions to access the cluster


-   (Optional) A [LangSmith](https://www.langchain.com/langsmith) API key for tracing


## [](#get-the-lab-files)Get the lab files

Clone the repository and navigate to the lab directory:

```bash
git clone https://github.com/redpanda-data/redpanda-labs.git
cd redpanda-labs/ai-agents/langchain-agent
```

## [](#set-up-the-project)Set up the project

1.  Install the project dependencies:

    ```bash
    poetry install
    ```

2.  Copy the example environment file and fill in your credentials:

    ```bash
    cp .env.example .env.local
    ```

3.  Edit `.env.local` with your Redpanda Cloud service account credentials:

    ```env
    REDPANDA_CLIENT_ID=<your-client-id>
    REDPANDA_CLIENT_SECRET=<your-client-secret>
    REDPANDA_GATEWAY_ID=<your-gateway-id>
    REDPANDA_GATEWAY_URL=<your-gateway-url>
    ```

    You can find these values in the [Redpanda Cloud console](https://cloud.redpanda.com).


## [](#run-the-agent)Run the agent

Start the agent:

```bash
poetry run redpanda-agent
```

The agent opens a terminal UI where you can interact with it. The agent authenticates with the AI Gateway using your service account credentials, discovers available MCP tools, and displays a chat prompt. From there, your requests are routed through the gateway to the configured LLM provider.

## [](#explore-the-lab)Explore the lab

Key technical components include the agent architecture, authentication flow, and dynamic tool discovery.

### [](#architecture)Architecture

The agent uses the following architecture:

```text
Python Agent (LangGraph)
  |
  |-- OIDC client_credentials flow --> Redpanda Cloud IdP --> Bearer token
  |
  |-- ChatOpenAI (base_url=<gateway-url>/v1)
  |       |
  |       +-- OpenAI-compatible API via gateway
  |
  |-- MCP tools via gateway (<gateway-url>/mcp/)
  |       |
  |       +-- tool_search --> discovers available tools dynamically
  |       +-- AgentMiddleware --> injects and executes discovered tools
  |
  |-- LangSmith tracing (optional)
```

### [](#how-the-ai-gateway-works)How the AI Gateway works

The AI Gateway is a multi-tenant platform where each user configures their own gateway instance. The gateway translates upstream provider responses into the OpenAI chat completions format, so clients interact with a standard interface regardless of the underlying model provider.

Every request to the gateway requires two headers:

| Header | Value | Purpose |
| --- | --- | --- |
| Authorization | Bearer <oidc_token> | OIDC authentication |
| rp-aigw-id | <your-gateway-id> | Identifies the gateway instance |

Because the gateway speaks the OpenAI format, you use `ChatOpenAI` from `langchain-openai`:

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url=f"{gateway_url}/v1",
    api_key="not-used",  # Auth is via OIDC Bearer token
    model="google/gemini-3-flash-preview",
    default_headers={
        "Authorization": f"Bearer {token}",
        "rp-aigw-id": gateway_id,
    },
)
```

### [](#oidc-authentication)OIDC authentication

Authentication is against the **Redpanda Cloud OIDC identity provider**, not the gateway itself. The gateway validates the resulting tokens.

The `GatewayAuth` class uses OIDC discovery to resolve the token endpoint automatically from the issuer:

```text
https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration
```

It fetches this discovery document on the first token request, then uses a `client_credentials` grant with the audience `cloudv2-production.redpanda.cloud`:

```python
auth = GatewayAuth()  # uses REDPANDA_ISSUER env var or default
token = await auth.get_token()
```

> 📝 **NOTE**
>
> The AI agent is responsible for refreshing tokens before they expire. `GatewayAuth` handles this automatically with a 30-second buffer before expiry.

### [](#dynamic-mcp-tool-discovery)Dynamic MCP tool discovery

The gateway’s MCP endpoint uses a two-level tool discovery pattern:

1.  `list_tools()` returns a small set of static tools, including `tool_search`.

2.  Calling `tool_search` discovers additional tools available on the gateway (such as `redpanda-docs:ask_redpanda_question`).

3.  The set of discovered tools can change at any time because they are not static.


The agent uses LangChain’s `AgentMiddleware` to inject dynamically discovered tools at runtime:

```python
from langchain.agents import create_agent

graph = create_agent(
    model=llm,
    tools=static_tools,       # For example, [tool_search]
    middleware=[middleware],   # MCPGatewayMiddleware
)
```

The `MCPGatewayMiddleware` provides two hooks:

-   `awrap_model_call`: Injects discovered tools into the model’s tool list before each LLM call.

-   `awrap_tool_call`: Intercepts calls to discovered tools and executes them through the MCP `ClientSession.call_tool()` method.


> 📝 **NOTE**
>
> MCP tool names like `redpanda-docs:ask_redpanda_question` contain colons, which are not valid in OpenAI tool names. The middleware sanitizes names by replacing invalid characters with hyphens and maintains a mapping to the original MCP name.

### [](#mcp-transport)MCP transport

Use `streamable_http` as the transport:

```python
client = MultiServerMCPClient({
    "gateway": {
        "transport": "streamable_http",
        "url": f"{gateway_url}/mcp/",
        "headers": { ... },
    },
})
```

### [](#enable-langsmith-tracing-optional)Enable LangSmith tracing (optional)

To enable tracing, set these environment variables in your `.env.local` file:

```env
LANGSMITH_API_KEY=<your-langsmith-api-key>
LANGSMITH_PROJECT=redpanda-agent
LANGSMITH_TRACING=true
```

LangGraph auto-detects these variables and traces all LLM and tool calls.

### [](#project-structure)Project structure

| File | Purpose |
| --- | --- |
| src/agent/auth.py | OIDC token management using authlib |
| src/agent/gateway.py | ChatOpenAI configured for the AI Gateway |
| src/agent/tools.py | MCP tool loading and AgentMiddleware for dynamic discovery |
| src/agent/graph.py | LangGraph agent graph |
| src/agent/main.py | Terminal UI entry point |

### [](#key-dependencies)Key dependencies

| Package | Purpose |
| --- | --- |
| langchain-openai | Gateway uses OpenAI format regardless of upstream provider |
| langchain-mcp-adapters | MCP client and tool conversion |
| authlib | OIDC client_credentials with token caching |

## [](#clean-up)Clean up

Stop the agent by pressing Ctrl+C in the terminal.

## [](#next-steps)Next steps

-   [Learn more about the AI Gateway](https://docs.redpanda.com/redpanda-cloud/ai-agents/ai-gateway/)