> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/sdk/agent-sdks · Doc index: https://docs.gatellm.io/en/llms.txt


# Agent SDKs

Agent SDKs add "tools, loops, multi-agent" orchestration on top of the model. Their common thread through the gateway is unchanged: **point the model provider at the gateway**. Unlike orchestration frameworks, they often ship an MCP client — the gateway's own `/mcp` endpoint can be attached as a tool server (see [MCP gateway proxy](/en/quickstart/mcp-proxy.md)).

## OpenAI Agents SDK (Python / TypeScript) {#openai-agents}

```bash
pip install openai-agents        # Python
npm i @openai/agents              # Node
```

> **Gotcha: defaults to the Responses API.** The OpenAI Agents SDK calls `/v1/responses` by default, not `/v1/chat/completions`. Through the gateway, if your model's upstream is `openai` (Chat) protocol, switch to Chat explicitly with `OpenAIChatCompletionsModel`; if the upstream is itself `openai_response`, a string model name works as-is.

::: code-group

```python [Python]
from agents import Agent, Runner, set_default_openai_client, set_tracing_disabled
from openai import AsyncOpenAI

# Point the SDK's default client at the gateway; disable tracing so traces don't hit the gateway too
client = AsyncOpenAI(base_url="http://localhost:7890/v1", api_key="<your access key>")
set_default_openai_client(client)
set_tracing_disabled(True)

# When the upstream is a Responses protocol, a string model name works (SDK defaults to /v1/responses)
agent = Agent(name="Assistant", instructions="Introduce yourself in one sentence", model="gpt-5.6-sol")
result = Runner.run_sync(agent, "Hi")
print(result.final_output)
```

```ts [TypeScript]
import { Agent, run, setDefaultOpenAIClient } from "@openai/agents";
import { OpenAI } from "openai";

// Point the SDK's default client at the gateway (mirrors the Python example)
const client = new OpenAI({ baseURL: "http://localhost:7890/v1", apiKey: "<your access key>" });
setDefaultOpenAIClient(client);

const agent = new Agent({
  name: "Assistant",
  instructions: "Introduce yourself in one sentence",
  model: "gpt-5.6-sol",
});

const result = await run(agent, "Hi");
console.log(result.finalOutput);
```

:::

When the upstream is `openai` (Chat) protocol, use `OpenAIChatCompletionsModel` to explicitly go through `/v1/chat/completions`:

```python
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel

model = OpenAIChatCompletionsModel(model="gpt-5.4-mini", openai_client=client)
agent = Agent(name="Assistant", instructions="Introduce yourself in one sentence", model=model)
result = Runner.run_sync(agent, "Hi")
print(result.final_output)
```

> Parameter names vary with the version (this section was run against `openai-agents` 0.22); follow the [OpenAI Agents SDK docs](https://openai.github.io/openai-agents-python/) for your installed version. `set_tracing_disabled(True)` avoids the SDK sending traces to the gateway and getting a 401.

## Claude Agent SDK (Python / TypeScript) {#claude-agent}

The Claude Agent SDK (`claude-agent-sdk`) shares its lineage with Claude Code and speaks the Anthropic protocol. It reads environment variables rather than constructor params — identical to [Connect Claude Code through the gateway](/en/quickstart/claude-code-via-gateway.md):

```bash
export ANTHROPIC_BASE_URL=http://localhost:7890
export ANTHROPIC_AUTH_TOKEN=<your access key>
export ANTHROPIC_MODEL=claude-haiku-4-5    # optional: align with the gateway model name
```

```python
from claude_agent_sdk import query

async for message in query(
    prompt="Introduce yourself in one sentence",
    options={"allowed_tools": ["Read"]},
):
    if message.type == "assistant":
        print(message.content)
```

> **Model-name alignment**: the agent sends the model ID it's configured with (e.g. `claude-sonnet-4-5`). Naming the gateway model exactly the ID the agent requests is the least friction, otherwise align via `ANTHROPIC_MODEL` — see [Connect Claude Code through the gateway](/en/quickstart/claude-code-via-gateway.md#configure-claude-code).

## Pydantic AI (Python) {#pydantic-ai}

```bash
pip install pydantic-ai openai
```

> Pydantic AI renamed its OpenAI model class across versions (`OpenAIModel` → `OpenAIChatModel`) — follow your installed version.

```python
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "gpt-5.4-mini",
    provider=OpenAIProvider(base_url="http://localhost:7890/v1", api_key="<your access key>"),
)
agent = Agent(model)

result = agent.run_sync("Introduce yourself in one sentence")
print(result.output)
```

## Google ADK (Python) {#google-adk}

Google ADK natively targets Gemini, but can be wrapped via LiteLLM to reach any OpenAI-compatible backend (including the gateway):

```python
from google.adk.models.lite_llm import LiteLlm
from google.adk.agents import Agent

model = LiteLlm(
    model="openai/gpt-5.4-mini",
    base_url="http://localhost:7890/v1",
    api_key="<your access key>",
)
agent = Agent(model=model, name="Assistant")
```

> This section is written per the official docs and not run in this environment; the LiteLLM wrapper params vary with the ADK version.

## Mastra (TypeScript) {#mastra}

Mastra is a full-stack agent framework; its model layer reuses the Vercel AI SDK providers — pass the `createOpenAICompatible` provider from [Unified SDKs & gateways](/en/sdk/unified-sdks.md#vercel-ai-sdk):

```ts
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { Agent } from "@mastra/core/agent";

const provider = createOpenAICompatible({
  name: "gatellm",
  baseURL: "http://localhost:7890/v1",
  apiKey: "<your access key>",
});

const agent = new Agent({
  name: "Assistant",
  model: provider("gpt-5.4-mini"),
  instructions: "Introduce yourself in one sentence",
});
```

> This section is written per the official docs and not run in this environment.

## Microsoft Agent Framework {#microsoft-agent}

Microsoft's cross-language agent framework (formerly AutoGen, now split into .NET / Python lines). The Python line is [AutoGen / AG2](/en/sdk/orchestration-frameworks.md#autogen); the .NET line points its OpenAI client at `http://localhost:7890/v1`. The wiring varies with the version — see the [Microsoft Agent Framework docs](https://learn.microsoft.com/agent-framework/) (not run in this environment).

## MCP SDK (attach the gateway's MCP as a tool server) {#mcp-sdk}

The gateway ships MCP endpoints (`/mcp`, `/mcp/sse`) that aggregate external tool servers. Any agent SDK can attach the gateway's `/mcp` as a **tool server** (like any ordinary MCP server), gaining the tools aggregated behind the gateway. Point the MCP client's URL at the gateway's `/mcp`:

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "http://localhost:7890/mcp",
        headers={"Authorization": "Bearer <your access key>"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

Full MCP gateway config (tool servers, ACL, context budget, BM25 search) — see [MCP config](/en/reference/mcp-config.md) and [MCP gateway proxy](/en/quickstart/mcp-proxy.md).

## Next {#next}

- Underlying model capabilities (image/embeddings/rerank/speech): see [Vendor SDKs](/en/sdk/vendor-sdks.md).
- Realtime voice interaction for agents: see [Realtime & audio](/en/sdk/realtime-and-audio.md).