先来看下最后实现的效果
主要内容
- SDK核心组件解析
- Demo实现的拆解:如何定义Agent,设置handoff;如何上游服务API对接或mock
- Tracing 和 真实生产的Todos
Demo场景和框架说明
业务场景是一个运输服务的司机端的智能客服,用户常见的问题场景一般都是关于资质审批,运单查询,录单之类 所以除了需要基础的Caht能力之外,还需要有稳定的ToolUse能力,当然还有成熟的Guardrails和Tracing组件
其实可以用的框架有很多,LangChain / AutoGPT / AutoGen等等。
选择 OpenAI Agents SDK 的优势
- • ✅ 业务场景适配快,Demo 实现便捷
- • ✅ 代码可读性强
- • ✅ 支持快速更换 LLM 模型
- 下文用的是SDK的Pyhon版本
https://github.com/openai/openai-agents-python
- 还有JavaScript/TypeScript的可以参考
https://github.com/openai/openai-agents-js/tree/main?tab=readme-ov-file
🛠️ 核心组件
1. Agent & Handoffs
核心是 Agent,可以自定义 instructions,并支持 Multi-Agent Handoffs(多智能体协作)。
2. Guardrails & Sessions & Tracing
SDK还提供了丰富的可观测性(Observability)生产必要组件,可以快速实现 日志以及调用链路(工具调用、模型推理)的追踪
安全护栏(Guardrails) 功能:可配置的输入输出安全检查机制 作用:过滤有害内容、验证数据格式、防止越权操作,确保Agent行为符合合规要求和伦理准则
会话管理(Sessions) 功能:跨运行周期的对话历史自动管理 作用:维持上下文连续性,支持长对话记忆,避免重复提问,提升交互连贯性
追踪系统(Tracing) 功能:Agent运行全流程记录与可视化 作用:提供执行链路追踪、错误定位、性能分析,支持工作流优化与调试
不过除了Tracing,其他内容Demo中暂时没有涉及。另外还有很多Agent设计模式,还有example可以参考哈,比如人工介入的处理
🎓 Demo 结构总览
整体框架如下图。主agent识别意图并分发给专业agent处理,实际功能实现由agent调用原有系统API
💬 Step 1 对话接入
一开始视频的效果,接入用户端使用了微信客服 当然其他任何用户端都是ok的,web / IM / 都可以,以下代码是直接在控制台对话
用户的对话通过接入层直接到main_agent
class AgentManager: """芝麻酱客服系统管理器""" def__init__(self): self.console = Console() asyncdefrun_interactive(self): """运行交互式客服系统""" self.print_welcome() whileTrue: try: # 获取用户输入 user_input = input("\n💬 请问有什么可以帮助您的?> ").strip() ifnot user_input: continue # 生成trace ID并开始处理 trace_id = gen_trace_id() with trace("芝麻酱客服对话", trace_id=trace_id): self.console.print(f"\n[dim]🔍 Trace ID: {trace_id}[/dim]") self.console.print("[bold blue]🤖 芝麻酱正在思考中...[/bold blue]") start_time = time.time() # 使用streaming模式运行agent result = Runner.run_streamed( main_agent, input=user_input ) .....asyncdefmain(): """主入口函数""" import sys manager = AgentManager() await manager.run_interactive()if __name__ == "__main__": asyncio.run(main())
🎯 Step 2 主 Agent 与意图识别
这里main_agent就是上文提到的主Agent。可以通过instructions来明确所有能力,以及什么情况下交由哪个专业Agent完成的handoffs
from agents import Agentmain_agent = Agent( name="Main_Agent", instructions="""你好!我是芝麻酱,贵公司的智能客服助手。我可以帮助您处理以下业务: 🚚 **运单添加**:处理运单的创建和录入 📋 **订单查询**:根据发货地查询已有的物流订单 我会根据您的需求将您转接给相应的专业同事: - 运单添加需求 → 转接运单添加专员 - 订单查询需求 → 转接订单查询专员 请告诉我您需要什么帮助,我会为您提供最专业的服务!""", handoffs=[ handoff( agent=logistics_add_agent, tool_name_override="handoff_to_logistics_add_agent", tool_description_override="当用户需要添加运单、录入运单信息、处理运单相关业务时使用" ), handoff( agent=order_query_agent, tool_name_override="handoff_to_order_query_agent", tool_description_override="当用户需要查询已有订单、根据发货地搜索订单、查看订单状态时使用" ) ],)
🔧 Step 3 分 Agent 与 Tool 实现
然后就可以分别定义handoff的agent,以及实现API调用的tool 比如录单的Agent,定义好需要什么参数,如何检查参数完整性。并且明确了什么时候使用 add_waybill的tool
录单 Agent
## 运单添加专员Agentlogistics_add_agent = Agent( name="Logistics_Add_Agent", instructions="""你是专业的运单添加专员。你的主要职责是:1. 收集完整的运单信息,包括运单号、货物详情、车辆和司机信息2. 确保所有必需的运单信息都已提供:运单号、发货地、卸货地、货物类型、货物重量、车牌号、司机姓名、司机电话、运费3. 如果信息不完整,询问用户补充缺失的信息4. 信息齐全后立即添加运单到系统工作流程:1. 接收用户的运单添加请求2. 逐一收集和确认运单信息3. 信息齐全后使用 add_waybill 工具添加运单4. 向用户反馈添加结果必需参数说明:- 运单号:唯一的运单编号(如:WB20241225001)- 发货地:货物发货地址- 卸货地:货物卸货地址 - 货物类型:运输的货物类型(如:钢材、电子产品等)- 货物重量:货物重量(如:10吨、500公斤)- 车牌号:运输车辆车牌号(如:京A12345)- 司机姓名:司机姓名- 司机电话:司机联系电话- 运费:运输费用(如:5000元)- 预计到达时间:可选参数重要:收集齐全所有必需信息后,立即使用add_waybill工具添加运单!""", tools=[add_waybill], handoff_description="专门处理运单的添加和录入", model_settings=ModelSettings(temperature=0.1))
查单 Agent
查单Agent也一样
## 订单查询专员Agentorder_query_agent = Agent( name="Order_Query_Agent", instructions="""你是专业的订单查询专员。你的主要职责是:1. 根据用户提供的发货地信息查询物流订单2. 支持模糊匹配查询,如用户输入"北京"可以匹配"北京市"、"北京朝阳区"等3. 将查询结果清晰地展示给用户4. 如果查询结果为空,提示用户尝试其他关键词工作流程:1. 接收用户的查询请求,提取发货地关键词2. 使用 query_logistics_orders 工具进行查询3. 格式化并展示查询结果4. 如果没有结果,建议用户尝试简化关键词或使用其他关键词查询说明:- 支持省份查询:如"北京"、"江苏"、"广东"等- 支持城市查询:如"上海"、"深圳"、"杭州"等 - 支持区域查询:如"朝阳"、"浦东"等- 查询不区分大小写,支持部分匹配""", tools=[query_logistics_orders], handoff_description="专门处理物流订单的查询和检索", model_settings=ModelSettings(temperature=0.1))
🔌 Step 4 Tool 实现(可 Mock)
对于录单agent的to…