> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/sdk/agent-sdks · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# Agent SDK

Agent SDK 在「模型」之上又叠了「工具、循环、多智能体」的编排。经网关用它们的共同点不变：**把模型 provider 指到网关**。与编排框架的区别是，它们常常自带 MCP 客户端——网关自己的 `/mcp` 端点可以作为工具服务器接进去（见 [MCP 网关代理](/zh-CN/quickstart/mcp-proxy.md)）。

## OpenAI Agents SDK（Python / TypeScript） {#openai-agents}

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

> **坑：默认走 Responses API**。OpenAI Agents SDK 默认调 `/v1/responses`，不是 `/v1/chat/completions`。经网关时，若你的模型上游是 `openai`（Chat）协议，要用 `OpenAIChatCompletionsModel` 显式切到 Chat；若上游本身就是 `openai_response`，用字符串模型名即可。

::: code-group

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

# 把 SDK 的默认客户端指向网关；关闭 tracing 以免 trace 也发到网关
client = AsyncOpenAI(base_url="http://localhost:7890/v1", api_key="<你的访问密钥>")
set_default_openai_client(client)
set_tracing_disabled(True)

# 上游为 Responses 协议时，字符串模型名即可（SDK 默认走 /v1/responses）
agent = Agent(name="助手", instructions="用一句话介绍你自己", model="gpt-5.6-sol")
result = Runner.run_sync(agent, "你好")
print(result.final_output)
```

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

// 把 SDK 的默认客户端指向网关（与 Python 示例一致）
const client = new OpenAI({ baseURL: "http://localhost:7890/v1", apiKey: "<你的访问密钥>" });
setDefaultOpenAIClient(client);

const agent = new Agent({
  name: "助手",
  instructions: "用一句话介绍你自己",
  model: "gpt-5.6-sol",
});

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

:::

上游是 `openai`（Chat）协议时，改用 `OpenAIChatCompletionsModel` 显式走 `/v1/chat/completions`：

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

model = OpenAIChatCompletionsModel(model="gpt-5.4-mini", openai_client=client)
agent = Agent(name="助手", instructions="用一句话介绍你自己", model=model)
result = Runner.run_sync(agent, "你好")
print(result.final_output)
```

> 参数名随版本变化（本节按 `openai-agents` 0.22 实跑），以你安装版本的 [OpenAI Agents SDK 官方文档](https://openai.github.io/openai-agents-python/) 为准。`set_tracing_disabled(True)` 是为了避免 SDK 把 trace 也发到网关而报 401。

## Claude Agent SDK（Python / TypeScript） {#claude-agent}

Claude Agent SDK（`claude-agent-sdk`）与 Claude Code 同源，走 Anthropic 协议。它读环境变量而非构造参数，与 [Claude Code 经网关接入](/zh-CN/quickstart/claude-code-via-gateway.md) 完全一致：

```bash
export ANTHROPIC_BASE_URL=http://localhost:7890
export ANTHROPIC_AUTH_TOKEN=<你的访问密钥>
export ANTHROPIC_MODEL=claude-haiku-4-5    # 可选：对齐网关模型名
```

```python
from claude_agent_sdk import query

async for message in query(
    prompt="用一句话介绍你自己",
    options={"allowed_tools": ["Read"]},
):
    if message.type == "assistant":
        print(message.content)
```

> **模型名对齐**：Agent 发请求时带的是它默认的模型 ID（如 `claude-sonnet-4-5`）。把网关模型**命名为 Agent 实际会请求的 ID** 最省事，否则用 `ANTHROPIC_MODEL` 对齐，详见 [Claude Code 经网关接入](/zh-CN/quickstart/claude-code-via-gateway.md#configure-claude-code)。

## Pydantic AI（Python） {#pydantic-ai}

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

> Pydantic AI 的 OpenAI 模型类随版本更名过（`OpenAIModel` → `OpenAIChatModel`），以你安装版本为准。

```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="<你的访问密钥>"),
)
agent = Agent(model)

result = agent.run_sync("用一句话介绍你自己")
print(result.output)
```

## Google ADK（Python） {#google-adk}

Google ADK 原生面向 Gemini，但可经 LiteLLM 包装接入任意 OpenAI 兼容后端（含网关）：

```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="<你的访问密钥>",
)
agent = Agent(model=model, name="助手")
```

> 本节按官方文档编写、未在本环境实跑；LiteLLM 包装器的参数随 ADK 版本变化。

## Mastra（TypeScript） {#mastra}

Mastra 全栈 Agent 框架，模型层复用 Vercel AI SDK 的 provider——把 [统一 SDK 与网关层](/zh-CN/sdk/unified-sdks.md#vercel-ai-sdk) 的 `createOpenAICompatible` provider 传进去即可：

```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: "<你的访问密钥>",
});

const agent = new Agent({
  name: "助手",
  model: provider("gpt-5.4-mini"),
  instructions: "用一句话介绍你自己",
});
```

> 本节按官方文档编写、未在本环境实跑。

## Microsoft Agent Framework {#microsoft-agent}

微软的跨语言 Agent 框架（前身 AutoGen，现分 .NET / Python 两线）。Python 线见 [AutoGen / AG2](/zh-CN/sdk/orchestration-frameworks.md#autogen)；.NET 线把其 OpenAI 客户端指向 `http://localhost:7890/v1` 即可，接法随版本变化，以 [Microsoft Agent Framework 官方文档](https://learn.microsoft.com/agent-framework/) 为准（未在本环境实跑）。

## MCP SDK（把网关的 MCP 当工具服务器） {#mcp-sdk}

网关自带 MCP 端点（`/mcp`、`/mcp/sse`），聚合外部工具服务器。任何 Agent SDK 都可以把网关的 `/mcp` 当**工具服务器**接进去（就像接一个普通 MCP server），从而拿到网关背后聚合的工具。配置 MCP 客户端时把 URL 指向网关的 `/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 <你的访问密钥>"},
    ) 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())
```

MCP 网关的完整配置（工具服务器、ACL、上下文预算、BM25 检索）见 [MCP 配置](/zh-CN/reference/mcp-config.md) 与 [MCP 网关代理](/zh-CN/quickstart/mcp-proxy.md)。

## 下一步 {#next}

- 底层模型能力（图像/向量/重排/语音）：看 [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md)。
- Agent 实时语音交互：看 [实时会话与语音](/zh-CN/sdk/realtime-and-audio.md)。