OpenAI Agent SDK — OpenAI 代理 SDK

OpenAI 代理 SDK 技能

使用 OpenAI 代理s SDK 构建多 代理 AI 系统。轻量级但强大的框架，支持 代理 协作、工具调用、交接机制和追踪调试。

何时使用此技能

当用户需要：

构建多 代理 协作系统 实现 代理 之间的任务交接 为 代理 添加工具（function calling） 创建智能路由和编排系统 实现人机协作（Human in the Loop） 构建语音 代理（Realtime 代理s） 需要追踪和调试 代理 工作流 核心概念

• 代理（智能体）

配置了指令、工具、防护栏和交接能力的 LLM。

from 代理s 导入 代理

代理 = 代理( name="助手", instructions="You are a helpful 助手", 工具s=[...], # 可选：工具列表 handoffs=[...], # 可选：可交接的其他 代理 模型="gpt-4", # 可选：模型选择 )

• 工具s（工具）

让 代理 执行动作的函数。

from 代理s 导入 function_工具 from typing 导入 Annotated

@function_工具 def 获取_weather(city: Annotated[str, "城市名称"]) -> str: """获取指定城市的天气信息""" return f"{city}：晴朗，20°C"

代理 = 代理(工具s=[获取_weather])

• 运行器（运行器）

执行 代理 的引擎，支持三种运行模式。

from 代理s 导入 运行器

# 同步运行 结果 = 运行器.运行_同步(代理, "Hello")

# 异步运行（推荐） 结果 = awAIt 运行器.运行(代理, "Hello")

# 流式运行 结果 = 运行器.运行_流ed(代理, "Hello") a同步 for event in 结果.流_事件(): print(event)

• Handoffs（交接）

代理 之间传递任务的机制。

french_代理 = 代理(name="French", instructions="只说法语") spanish_代理 = 代理(name="Spanish", instructions="只说西班牙语")

triage_代理 = 代理( name="Triage", instructions="根据语言分配给合适的 代理", handoffs=[french_代理, spanish_代理], )

• 代理s as 工具s（代理 作为工具）

将 代理 封装为工具供其他 代理 调用。

translator = 代理(name="Translator", ...)

编排器 = 代理( name="编排器", 工具s=[ translator.as_工具( 工具_name="translate", 工具_description="翻译文本" ) ], )

• 防护rAIls（防护栏）

输入输出验证和安全检查。

from 代理s 导入 输入_防护rAIl, 防护rAIlFunction输出

@输入_防护rAIl def 检查_输入(ctx, 代理, 输入): if "敏感词" in 输入: return 防护rAIlFunction输出( 输出_信息="包含敏感内容", tripwire_triggered=True ) return 防护rAIlFunction输出( 输出_信息="验证通过", tripwire_triggered=False )

代理 = 代理(输入_防护rAIls=[检查_输入])

• Tracing（追踪）

内置的运行追踪和调试。

from 代理s 导入 追踪

with 追踪("我的工作流"): 结果 = awAIt 运行器.运行(代理, "任务")

• 会话s（会话）

自动管理对话历史。

from 代理s 导入 会话

会话 = 会话() 结果1 = awAIt 运行器.运行(代理, "问题1", 会话=会话) 结果2 = awAIt 运行器.运行(代理, "问题2", 会话=会话) # 记住问题1的上下文

快速开始 安装 # 使用 pip pip 安装 openAI-代理s

# 使用 uv uv 添加 openAI-代理s

# 带语音支持 pip 安装 'openAI-代理s[voice]'

# 带 Redis 会话支持 pip 安装 'openAI-代理s[redis]'

设置环境变量 导出 OPENAI_API_KEY="sk-your-API-key-here"

Hello World 示例 导入 a同步io from 代理s 导入 代理, 运行器

a同步 def mAIn(): 代理 = 代理( name="助手", instructions="You are a helpful 助手", ) 结果 = awAIt 运行器.运行(代理, "Write a hAIku about programming.") print(结果.final_输出)

if __name__ == "__mAIn__": a同步io.运行(mAIn())

常见设计模式 模式 1: 路由（Routing）

根据输入类型分配给不同的专业 代理。

sales_代理 = 代理(name="Sales", instructions="处理销售相关咨询") support_代理 = 代理(name="Support", instructions="处理技术支持") technical_代理 = 代理(name="Technical", instructions="处理技术问题")

triage_代理 = 代理( name="Triage", instructions="根据用户请求类型分配给合适的 代理", handoffs=[sales_代理, support_代理, technical_代理], )

模式 2: 编排者（编排器）

一个主 代理 协调多个专业 代理。

re搜索er = 代理(name="Re搜索er", instructions="搜索和收集信息") analyst = 代理(name="Analyst", instructions="分析数据") writer = 代理(name="Writer", instructions="撰写报告")

编排器 = 代理( name="编排器", instructions="协调各个专业 代理 完成复杂任务", 工具s=[ re搜索er.as_工具(工具_name="re搜索", 工具_description="搜索信息"), analyst.as_工具(工具_name="analyze", 工具_description="分析数据"), writer.as_工具(工具_name="write", 工具_description="撰写内容"), ], )

模式 3: 并行执行（Parallelization）

多个 代理 同时执行独立任务。

导入 a同步io

a同步 def parallel_工作流(): 结果s = awAIt a同步io.gather( 运行器.运行(代理1, 输入), 运行器.运行(代理2, 输入), 运行器.运行(代理3, 输入), ) return 结果s

模式 4: 人机协作（Human in the Loop）

在关键决策点请求人工确认。

from 代理s 导入 代理, 运行器

代理 = 代理( name="助手", instructions="帮助用户做决策，在重要决策前请求确认", )

# 使用流式输出来实现实时交互 结果 = 运行器.运行_流ed(代理, "帮我规划旅行") a同步 for event in 结果.流_事件(): # 检测需要人工确认的事件 if needs_human_应用roval(event): 应用roval = awAIt 获取_human_输入() # 继续执行

高级功能 使用其他 LLM

SDK 支持通过 LiteLLM 接入 100+ LLM。

from 代理s 导入 代理 from openAI 导入 A同步OpenAI

# 使用 Anthropic Claude claude_命令行工具ent = A同步OpenAI( API_key="your-anthropic-key", base_url="https://API.anthropic.com/v1" )

代理 = 代理( name="Claude代理", 模型="claude-3-opus-20240229", 模型_设置tings={"命令行工具ent": claude_命令行工具ent} )

Realtime 代理s（语音 代理） from 代理s 导入 代理, 运行器 from 代理s.voice 导入 Voice代理

voice_代理 = VoiceAgen