从 Claude Agent SDK 迁移到 OpenAI Agents SDK

来源: https://developers.openai.com/cookbook/examples/agents_sdk/migrate-from-claude-agent-sdk/readme 抓取时间: 2026-07-21 16:26:35

为什么迁移

更新后的 OpenAI Agents SDK 为团队提供了模型原生的框架，用于构建可以在工具、文件、内存、审批和沙箱计算之间协调的智能体。它是开源的，因此团队可以检查和自定义运行时行为。您不必为每个模型集成重新构建这些组件，而是可以使用一个标准的 SDK，保持核心智能体循环可见和可自定义。 许多 Claude Agent SDK 应用程序遵循 Claude Code 操作模型：加载项目指令、加载技能、暴露文件/Shell/Web 工具、可选地定义子智能体，并让 Claude 框架在工作区内操作。新的 OpenAI Agents SDK 为团队提供了智能体框架与计算环境之间更明确的分离。 最重要的架构区别：

• Claude Agent SDK 模式： 框架在沙箱内运行。沙箱包含智能体循环、MCP/工具、文件系统访问和执行环境。
• 新的 OpenAI Agents SDK 模式： 框架与计算分离。可信应用程序运行时拥有智能体循环、工具、审批、机密、护栏、追踪和业务系统访问。

通过本指南，您应该拥有一个已迁移的应用程序，该程序保留了原始 Claude 应用程序的行为，同时使执行、安全性、状态和所有权明确。

架构

沙箱作为工具

Claude Agent SDK 应用程序遵循 Claude Code 操作模型：沙箱是智能体的主要工作区。智能体循环、工具、文件系统和执行环境通常共存。网关可能位于沙箱和内部系统之间，以便沙箱可以在不直接持有敏感凭据的情况下发出受控请求。 Claude Agent SDK 应用程序通常将框架和执行环境放在同一个沙箱边界内。

在 OpenAI Agents SDK 模式中，框架与计算（沙箱）分离。沙箱是框架可以调用的工具，当智能体需要作用域计算、文件系统访问、代码执行、工件或可执行技能时。 OpenAI Agents SDK 应用程序在可信运行时中保持编排，并将沙箱用作执行面。

将受信任的控制保留在宿主应用程序中，并且仅将沙箱用于以工作区为中心的执行。 这更安全、更容易操作，因为机密、审批决策和业务系统访问都保留在执行环境之外。应用程序控制沙箱的输入、输出和审批。

技能和指令文件

迁移 Claude Agent SDK 项目时，按职责拆分指令和技能文件。

分离智能体身份、可重用工作流、参考材料、可执行逻辑和运行时配置。

生命周期回调和权限

Claude 生命周期回调可以检查工具调用，决定是否应该继续、阻止或请求权限。OpenAI 生命周期回调的工作方式不同。它们告诉您的应用程序运行期间发生的事情，但它们不是审批和权限的主要位置。 将只读 Claude 回调（例如日志记录或遥测）迁移到 OpenAI 回调。将批准或重塑执行的 Claude 回调迁移到 OpenAI 护栏或审批。

子智能体和所有权

OpenAI Agents SDK 使智能体所有权明确。 当主智能体应保持控制、调用专家、组合它们的输出并生成最终答案时，请使用 agent.as_tool(...)。 当专家应接管对话并拥有最终响应时，请使用 handoffs=[...]。

您迁移的内容

大多数迁移归结为十个决策：

首先确定每个 Claude 功能提供的行为，然后选择可以保留该行为并具有正确执行和安全边界的 OpenAI 界面。

运行示例：航班预订助手

本指南使用示例航班预订助手作为运行示例。 Claude 基线应用：

• 搜索可用的航班。
• 检查旅行政策。
• 在存在时推荐合规选项。
• 在选项超出政策时推荐升级。

示例用户请求：

Book SFO to JFK on 2026-05-10 under $700.

共享域行为

下面的 Claude 和 OpenAI 示例使用此数据和策略规则。

from dataclasses import asdict, dataclass


@dataclass
class Flight:
    flight_id: str
    origin: str
    destination: str
    date: str
    departure_time: str
    arrival_time: str
    price_usd: int
    refundable: bool


FLIGHTS = [
    Flight("AS-301", "SFO", "JFK", "2026-05-10", "08:10", "16:45", 642, True),
    Flight("UA-882", "SFO", "JFK", "2026-05-10", "11:20", "19:58", 735, True),
    Flight("DL-441", "SFO", "JFK", "2026-05-10", "13:05", "21:35", 689, False),
]


def flight_to_dict(flight: Flight) -> dict:
    return asdict(flight)


def find_flight(flight_id: str) -> Flight | None:
    return next((flight for flight in FLIGHTS if flight.flight_id == flight_id), None)


def policy_verdict(flight: Flight, max_price_usd: int) -> dict:
    within_budget = flight.price_usd <= max_price_usd
    compliant = within_budget and flight.refundable
    reasons = []

    if not within_budget:
        reasons.append(f"price_usd exceeds max_price_usd={max_price_usd}")
    if not flight.refundable:
        reasons.append("flight is non-refundable")

    return {
        "flight_id": flight.flight_id,
        "compliant": compliant,
        "reasons": reasons or ["within budget and refundable"],
    }

基线 Claude Agent SDK 实现

在 Claude Agent SDK 中，ClaudeAgentOptions 配置智能体行为。 工具暴露和工具审批是单独的控制。tools 选择内置 Claude Code 工具的基本集合，mcp_servers 将 MCP 服务器工具添加到会话中。allowed_tools 是权限允许列表：匹配的工具调用会自动获得批准，但未列出的工具不会从 Claude 的工具集中删除。 对于此示例，Claude 应用程序添加一个进程内 MCP 服务器，带有两个自定义业务工具，然后自动批准这两个工具调用，以便演示可以在没有审批提示的情况下运行：

• search_flights — 按路线、日期和预算检索候选航班。
• check_travel_policy — 评估候选航班的预算和退款政策。

Claude 自定义工具

from typing import Any
import asyncio
import json

from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    ResultMessage,
    TextBlock,
    create_sdk_mcp_server,
    tool,
)


@tool(
    "search_flights",
    "Search flights for a route and date under a maximum budget.",
    {
        "type": "object",
        "properties": {
            "origin": {"type": "string"},
            "destination": {"type": "string"},
            "date": {"type": "string"},
            "max_price_usd": {"type": "integer"},
        },
        "required": ["origin", "destination", "date"],
    },
)
async def search_flights(args: dict[str, Any]) -> dict[str, Any]:
    max_price_usd = args.get("max_price_usd", 9999)
    matches = [
        flight_to_dict(flight)
        for flight in FLIGHTS
        if flight.origin == args["origin"]
        and flight.destination == args["destination"]
        and flight.date == args["date"]
        and flight.price_usd <= max_price_usd
    ]
    return {
        "content": [
            {"type": "text", "text": json.dumps({"flights": matches})}
        ]
    }


@tool(
    "check_travel_policy",
    "Check whether a flight is compliant with travel policy.",
    {
        "type": "object",
        "properties": {
            "flight_id": {"type": "string"},
            "max_price_usd": {"type": "integer"},
        },
        "required": ["flight_id", "max_price_usd"],
    },
)
async def check_travel_policy(args: dict[str, Any]) -> dict[str, Any]:
    flight = find_flight(args["flight_id"])
    if flight is None:
        return {
            "content": [
                {
                    "type": "text",
                    "text": json.dumps(
                        {"flight_id": args["flight_id"], "error": "not_found"}
                    ),
                }
            ],
            "is_error": True,
        }

    verdict = policy_verdict(flight, args["max_price_usd"])
    return {"content": [{"type": "text", "text": json.dumps(verdict)}]}

Claude 运行循环

travel_tools = create_sdk_mcp_server(
    name="travel",
    version="1.0.0",
    tools=[search_flights, check_travel_policy],
)

options = ClaudeAgentOptions(
    system_prompt=(
        "You help users evaluate flight options. "
        "Always search flights and check travel policy before recommending. "
        "Recommend a compliant option when one exists. "
        "If no compliant option exists, recommend escalation instead. "
        "Do not purchase tickets or charge a card."
    ),
    mcp_servers={"travel": travel_tools},
    # 预先批准这些旅行 MCP 工具，以便演示运行时没有权限提示。
    # 这不会隐藏或禁用其他工具。
    # 使用 `tools` 和/或 `disallowed_tools` 进行硬性可用性限制。
    allowed_tools=[
        "mcp__travel__search_flights",
        "mcp__travel__check_travel_policy",
    ],
)


async def main() -> None:
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Book SFO to JFK on 2026-05-10 under $700.")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

            if isinstance(message, ResultMessage) and message.subtype == "success":
                print("FINAL:", message.result)


asyncio.run(main())

预期结果：助手应推荐 AS-301，因为它是请求日期从 SFO 到 JFK 的航班，价格为 642 美元，并且可退款。它不应该推荐 DL-441，即使它低于 700 美元，因为政策要求可退款票价。

Claude 基线建立了什么

迁移路径：从 Claude 基线到 OpenAI

OpenAI 迁移的自定义工具

业务操作成为 Python 函数。函数名称、类型提示、文档字符串和返回值成为面向模型的工具契约。

from agents import Agent, Runner, function_tool


@function_tool
def search_flights(
    origin: str,
    destination: str,
    date: str,
    max_price_usd: int = 9999,
) -> list[dict]:
    """Search flights for a route and date under a maximum budget."""
    return [
        flight_to_dict(flight)
        for flight in FLIGHTS
        if flight.origin == origin
        and flight.destination == destination
        and flight.date == date
        and flight.price_usd <= max_price_usd
    ]


@function_tool
def check_travel_policy(flight_id: str, max_price_usd: int) -> dict:
    """Check whether a flight is compliant with travel policy."""
    flight = find_flight(flight_id)
    if flight is None:
        return {"flight_id": flight_id, "error": "not_found"}
    return policy_verdict(flight, max_price_usd)

OpenAI 迁移的智能体和运行循环

将 MODEL 和 GUARDRAIL_MODEL 设置为任何当前支持 Responses 的模型，这些模型支持您的应用程序使用的 Agents SDK 功能。

MODEL = "gpt-5.5"
GUARDRAIL_MODEL = "gpt-5.5-mini"


agent = Agent(
    name="Flight Booking Assistant",
    model=MODEL,
    instructions=(
        "You help users evaluate flight options. "
        "Always search flights and check travel policy before recommending. "
        "Recommend a compliant option when one exists. "
        "If no compliant option exists, recommend escalation instead. "
        "Do not purchase tickets or charge a card."
    ),
    tools=[search_flights, check_travel_policy],
)

result = await Runner.run(
    agent,
    "Book SFO to JFK on 2026-05-10 under $700.",
)
print(result.final_output)

预期结果：助手应推荐 AS-301，因为它是请求日期从 SFO 到 JFK 的航班，价格为 642 美元，并且可退款。它不应该推荐 DL-441，即使它低于 700 美元，因为政策要求可退款票价。

分步迁移

步骤 1：定义第一个 OpenAI 智能体

如果一个 Claude 智能体端到端处理单个任务，通常映射到一个 OpenAI Agent。 对于航班预订示例：

• 智能体： 航班预订助手
• 职责： 搜索航班、检查政策并推荐预订或升级。

步骤 2：移植自定义工具

按以下顺序移植自定义工具：

1. 保持业务操作不变。
2. 收紧函数签名。
3. 编写解释何时使用该工具的函数文档。
4. 返回智能体可以检查的结构化数据。

默认规则： 按行为映射自定义工具。search_flights 或 check_travel_policy 等域操作成为 @function_tool 函数。不要将通用文件或 Shell 原语作为自定义业务工具移植。

步骤 3：按执行边界映射内置工具

Claude 应用程序通常暴露文件/bash 工具。在迁移期间，不要将它们创建为自定义业务工具。 对业务或域操作使用 @function_tool。对 OpenAI 托管的检索或执行使用托管工具。对偶尔的本地/运行时操作使用 ShellTool 或 ApplyPatchTool。当任务需要隔离的工作区时，使用带有沙箱功能的 SandboxAgent。

注意：如果 Claude 应用程序定义了自定义帮助程序，如 read_file、write_file、grep_files 或 run_bash，请避免 1:1 移植它们。将文件读取、编辑、搜索和 Shell 命令映射到具有沙箱工作区的最接近的内置 OpenAI 工具。

步骤 4：将验证移动到正确的护栏边界

如果您的 Claude 应用程序依赖钩子来阻止操作、要求审批或更改执行行为，请将该逻辑映射到正确的 OpenAI 模式：护栏、审批或钩子。 使用护栏进行应在运行开始、工具执行或最终答案返回之前进行的验证。

示例：在工具运行之前需要核心预订字段。 首先定义护栏，然后将其附加到航班预订智能体。将护栏设置为在阻止模式下运行，会在主智能体可以调用任何工具之前检查请求。默认情况下，输入护栏与主智能体并行运行，以降低延迟。在这里我们设置 run_in_parallel=False，因为此验证必须在允许智能体开始使用工具之前完成。

from pydantic import BaseModel
from agents import (
    Agent,
    GuardrailFunctionOutput,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
)


class BookingRequestCheck(BaseModel):
    is_flight_booking_request: bool
    has_route: bool
    has_date: bool
    has_budget: bool
    reasoning: str


booking_guardrail_agent = Agent(
    name="Booking request guardrail",
    model=GUARDRAIL_MODEL,
    instructions=(
        "Decide whether the user is asking for a flight-booking recommendation. "
        "The request is ready only if it includes a route, travel date, and budget."
    ),
    output_type=BookingRequestCheck,
)


@input_guardrail(run_in_parallel=False)
async def require_ready_booking_request(
    ctx: RunContextWrapper[None],
    agent: Agent,
    user_input: str | list[TResponseInputItem],
) -> GuardrailFunctionOutput:
    result = await Runner.run(
        booking_guardrail_agent,
        user_input,
        context=ctx.context,
    )
    check = result.final_output
    ready = (
        check.is_flight_booking_request
        and check.has_route
        and check.has_date
        and check.has_budget
    )
    return GuardrailFunctionOutput(
        output_info=check,
        tripwire_triggered=not ready,
    )


agent = Agent(
    name="Flight Booking Assistant",
    model=MODEL,
    instructions=(
        "You help users evaluate flight options. "
        "Always search flights and check travel policy before recommending. "
        "Recommend a compliant option when one exists. "
        "If no compliant option exists, recommend escalation instead. "
        "Do not purchase tickets or charge a card."
    ),
    tools=[search_flights, check_travel_policy],
    input_guardrails=[require_ready_booking_request],
)

步骤 5：选择多智能体所有权

两种规范模式：

• 当管理智能体应保持最终响应所有者时，请使用 agent.as_tool(...)。
• 当专家应接管并拥有最终响应时，请使用 handoffs=[...]。

关键问题是所有权。

模式 A：专家作为工具

当主要编排智能体应保持控制时，请使用此模式。专家作为工具运行，返回狭窄的结果，并让编排器决定下一步做什么以及如何回答用户。

from agents import Agent, ModelSettings, Runner


pricing_specialist = Agent(
    name="Pricing Specialist",
    model=MODEL,
    instructions="Analyze candidate flights and return a short pricing verdict.",
)

manager = Agent(
    name="Travel Manager",
    model=MODEL,
    instructions=(
        "Call pricing_tool first, then give the final customer-facing recommendation yourself."
    ),
    tools=[
        pricing_specialist.as_tool(
            tool_name="pricing_tool",
            tool_description="Analyze flight pricing and policy fit.",
        )
    ],
    model_settings=ModelSettings(tool_choice="required"),
)

# 预期最终所有者：Travel Manager。

模式 B：交接给专家

当专家智能体应接管时，请使用此模式。编排器移交对话，专家智能体负责后续步骤和最终响应。

booking_specialist = Agent(
    name="Booking Specialist",
    model=MODEL,
    instructions="You own final flight-booking recommendations once transferred.",
)

triage = Agent(
    name="Travel Triage",
    model=MODEL,
    instructions="Always hand off flight-booking tasks to Booking Specialist.",
    handoffs=[booking_specialist],
    model_settings=ModelSettings(tool_choice="required"),
)

# 预期最终所有者：Booking Specialist。

步骤 6：选择一个对话状态策略

重要区别：对话延续将上下文带入新回合；运行状态恢复在中断后继续同一个暂停的运行。

步骤 7：为需要人工审查的副作用添加审批

当操作应要求人工审批时，请使用审批，例如刷卡、删除数据或更改生产状态。 审批生命周期：

1. 运行到达审批点。
2. 运行暂停。
3. 中断浮出水面以供审查。
4. 应用程序批准或拒绝。
5. 同一运行从 RunState 恢复。

@function_tool(needs_approval=True)
async def add_checked_bag(booking_id: str, bags: int) -> dict:
    """Add checked bags to an existing booking after human approval."""
    return {
        "booking_id": booking_id,
        "bags_added": bags,
        "status": "submitted",
    }


first = await Runner.run(agent, "Add one checked bag to booking AS-301.")
state = first.to_state()

for interruption in first.interruptions:
    state.approve(interruption)  # or state.reject(interruption)

resumed = await Runner.run(agent, state)
print("FINAL:", resumed.final_output)

最终验证清单

在组合完整应用程序之前，一次检查一个构建块的迁移。

推荐的测试顺序

1. 使用迁移的自定义工具运行基线智能体。
2. 添加输入和输出护栏。
3. 仅在需要时添加工具级检查。
4. 添加专家智能体。
5. 使用 agent.as_tool(...) 或 handoffs=[...] 检查所有权。
6. 添加对话延续。
7. 添加副作用审批。
8. 如果工作流程需要隔离，请添加沙箱。
9. 并排运行 Claude 和 OpenAI 场景。
10. 比较最终答案质量、工具调用、安全行为和状态处理。

结论

成功的迁移保留了业务任务并更新了执行模型。

• 在隔离重要的地方添加沙箱。 OpenAI 的 Agents SDK 将受信任的应用程序与发生有风险或有状态工作的工作区分开。当智能体需要作用域文件、命令执行、工件或可恢复工作区状态时，请使用沙箱。
• 将业务操作作为显式工具迁移。 搜索航班或创建票务等操作应成为具有类型化输入和可预测输出的清晰业务工具。不要重建通用 Shell 或文件访问作为业务工具。
• 保持工具访问和审批分离。 在 Claude 中，工具选择和预先批准可能看起来相关。在 OpenAI 模型中，首先决定智能体可以看到哪些工具。然后为需要人工审查的操作添加审批检查。
• 适当使用护栏和审批。 使用护栏检查请求和输出。使用审批暂停有风险的副作用。使用生命周期回调进行日志记录、追踪和审计事件。
• 对于多智能体所有权，当主要智能体应保持负责时，请使用 agent.as_tool(...)。 当专家应拥有最终响应时，请使用 handoffs=[...]。