Skip to content
AI Blog

Agents SDK 与 Apps SDK 入门

最后更新：2026-08-12· 16 分钟阅读

🚀 快速通道

  • ChatGPT 国内版：点击直达↗
  • 稳定镜像站：打开镜像↗
  • 官方 ChatGPT：chatgpt.com ↗

Agents SDK 与 Apps SDK 入门

更新时间：2026-08-12

导读

单次 responses.create 足够回答 FAQ；当流程变成「识别意图 → 查库 → 调 HTTP → 转人工 → 输出 JSON」时，手写 tool 循环会很快失控。Agents SDK 把 Agent、Tool、Handoff、Guardrail 封装成可测试的编排层，底层仍走 Responses API。Apps SDK 则面向在 ChatGPT 客户端 内分发交互式应用。类名、包名、支持语言以 Agents 文档 与官方 GitHub 为准——示例 import 上线前务必对照最新 repo。

核心概念速览

Runner.run(Agent, user_input)
  → LLM：直接答 | call Tool | Handoff 到其他 Agent
  → Guardrail 拦截不合规输入 / 输出
  → trace 记录每步 → final_output
概念作用
Agentinstructions + model + tools 的配置包
Tool函数、检索、MCP 等可执行能力
Handoff动态把会话交给专精 Agent
GuardrailPII、越狱、格式校验
Runner驱动多轮推理—执行循环

SDK 是编排层，不是新模型；费用仍来自 Responses 的 token 与工具调用。

选型：Agents SDK 还是纯 Responses？

无工具、单轮？ ──是──→ responses.create 即可
       │
       否
       ↓
固定 1–2 工具、≤3 步？ ──是──→ 手写 tool 循环（更简单）
       │
       否
       ↓
多 Agent 分工 / 需要 trace？ ──是──→ Agents SDK
场景推荐
FAQ、单次摘要纯 Responses
固定查单 + 回复手写 1 个 function 循环
客服分流、专精 AgentAgents SDK + Handoff
排障、审计每步调用Agents SDK trace
ChatGPT 内公开分发Apps SDK

原则： 先用 Responses 跑通 MVP，复杂度上升再引入 Agents SDK——避免过度设计。

Python 最小示例

import 路径以官方 repo 为准，以下为概念代码：

from agents import Agent, Runner, function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """查询订单状态（示例：应接真实 DB）"""
    return f"订单 {order_id}：已发货"

agent = Agent(
    name="OrderBot",
    instructions="你是电商助手。查单用 get_order_status，中文简洁回答。",
    tools=[get_order_status],
    model="gpt-4o",  # 以 Models 页当前 ID 为准
)

result = Runner.run_sync(agent, "订单 8821 到哪了？")
print(result.final_output)

Handoff 分流

billing = Agent(name="Billing", instructions="只处理发票与退款")
general = Agent(
    name="General",
    instructions="一般问题直接答；账单类 handoff 给 Billing",
    handoffs=[billing],
)

Handoff 让各 Agent 的 instructions 保持短小，独立 eval 与迭代。

Guardrails 与副作用安全

层级示例
输入 Guardrail拦截 PII、越狱、超长 payload
输出 GuardrailJSON schema、禁止泄露 system
工具层订单 ID 格式、频率限制、权限校验

不可省略： 转账、删数据、发邮件等副作用必须在服务端二次校验；Guardrail 是辅助，不是唯一防线。

可观测性与评测

  • SDK trace / span：看清每步 model 与 tool，缩短排障时间
  • 每个 Agent 独立 eval 集（官方 evals 文档）
  • 子任务可用 Fine-tuning 提升分类 / 格式；编排层仍用 Agents

Apps SDK：ChatGPT 生态

Agents SDKApps SDK
运行处你的服务器ChatGPT 客户端 surface
目标用户内部 copilot、后台自动化终端用户、平台发现
认证你的 API Key / OAuth平台审核 + 连接规范
典型客服编排、ETLSaaS 的 ChatGPT 入口

Manifest、OAuth、审核流程见 OpenAI Apps 开发者文档；与 Platform 项目可能分开配置。

与 Assistants 的关系

Assistants（Thread / Run / Vector Store）是较早托管形态；官方引导新能力向 Responses + Agents SDK 收敛。存量见 Assistants 指南；新项目勿重复投资 Thread 模型。

参考架构

用户 → ChatGPT App (Apps SDK) 或 你的 API
         → Agents SDK（handoff / guardrails）
           → Responses API
             → 业务 DB | [Embeddings RAG](/zh-cn/guides/openai-dev/embeddings/) | HTTP

多模态输入见 Vision 指南。

常见问题

Agents SDK 单独收费吗？

SDK 开源；费用来自底层 model 与托管工具。见 定价页。

只有 Python 吗？

官方通常多语言；概念跨语言一致，以 repo 为准。

Handoff 和 Fine-tuning 都管路由？

Handoff 是运行时路由；微调改权重。意图稳定时 handoff + 小模型常够用。

国内能用 Apps SDK 吗？

受平台政策、OAuth、网络影响；需完成 OpenAI 开发者注册与合规要求。

Agent 无限调工具怎么办？

设 max_turns；每个 tool 设超时、幂等与调用上限。

官方资源

下一步阅读

行动路径

今天：读 Agents Quickstart，跑通单 Agent + 单 tool。明天：加 Handoff 第二个 Agent，用 5 条多意图 query 测路由。本周：为危险 tool 加服务端校验 + trace；若需 ChatGPT 分发再评估 Apps SDK 注册。

相关内容