文章目录
- 说明
- [一 Agents-SDK简介](#一 Agents-SDK简介)
- [二 Agents SDK基础入门](#二 Agents SDK基础入门)
-
- [2.1 接入DeepSeek模型并测试](#2.1 接入DeepSeek模型并测试)
- [2.2 Agents SDK安装与调用](#2.2 Agents SDK安装与调用)
- [三 构造多轮对话机器人](#三 构造多轮对话机器人)
-
- [3.1 具体响应结果特点](#3.1 具体响应结果特点)
- [3.2 多轮对话完整代码](#3.2 多轮对话完整代码)
- [3.3 多轮对话内容](#3.3 多轮对话内容)
- [四 接入ollama/vLLM本地模型](#四 接入ollama/vLLM本地模型)
说明
- 本文学自赋范社区公开课，仅供学习和交流使用，不用作任何商业用途！
一 Agents-SDK简介
- Agents-SDK是一款企业级Multi-Agent开发框架，该框架是的Swarm的升级版，在保留了Swarm的高效便捷的Multi-Agent开发特性的同时，加入了更多面向企业级应用的功能。
- openai agents github
- Agents SDK博客
OpenAI Agents SDK能够通过一个轻量、易用、抽象极少的工具包来构建基于智能体的 AI 应用。该 SDK 仅包含极少量的原语（基础构件）：Agent（智能体）：即带有指令和工具的大语言模型（LLM）Handoff（交接）：允许智能体将特定任务委托给其他智能体Guardrail（护栏）：用于对输入内容进行验证
- 此外，SDK 自带内置的追踪功能，可以帮助你可视化和调试智能体的执行流程，同时也支持对流程进行评估，甚至用于模型的微调。结合 Python 和原语，能够表达工具与智能体之间的复杂关系，构建真实可用的应用程序。
- OpenAI的Agents SDK 的设计遵循两个核心原则：
- 功能足够强大，值得使用，但原语足够少，容易上手。
- 默认配置即可很好地运行，但你也可以完全自定义行为逻辑。
- SDK 的主要特性：
- Agent 循环机制：内置的智能体循环逻辑，自动处理工具调用、结果返回给 LLM、直到任务完成的全过程
- Python 优先：使用原生 Python 语言特性来编排与串联智能体，而无需学习新的抽象概念
- Handoff（智能体间任务交接）：强大的功能，可在多个智能体间协调与任务委派
- Guardrail（输入验证护栏）：支持与智能体并行运行输入验证逻辑，若验证失败可提前中断流程
- 函数工具化：可以将任何 Python 函数转为工具，自动生成 Schema，并支持基于 Pydantic 的验证机制
- 追踪系统（Tracing）：内置追踪功能，可视化、调试、监控你的智能体流程，并结合 OpenAI 的评估、微调与蒸馏工具一同使用。
二 Agents SDK基础入门
- 安装并验证openai模块
python
pip install openai
import openai
openai.__version__2.1 接入DeepSeek模型并测试
python
from openai import OpenAI
OPENAI_API_KEY="hk-xx"
OPENAI_API_BASE="https://api.openai-hk.com/v1"
MODEL="deepseek-v3"
# 实例化客户端
client = OpenAI(api_key=OPENAI_API_KEY,
base_url=OPENAI_API_BASE)
# 调用 deepseekv3 模型
response = client.chat.completions.create(
model=MODEL,
messages=[
{"role": "user", "content": "你好，好久不见!请介绍下你自己。"}
]
)
# 输出生成的响应内容
print(response.choices[0].message.content)你好呀！很高兴再次相遇！😊 我是 DeepSeek Chat ，由深度求索公司打造的智能 AI 助手。我的最新版本是 DeepSeek-V3 ，知识更新至 2024年7月，拥有强大的文本理解和生成能力，可以帮助你解答各种问题，包括学习、工作、编程、生活百科等。
✨ 我的特点：
- 免费使用：目前无需付费，随时为你服务！
- 超长上下文 ：支持 128K 上下文记忆，可以处理超长文档和复杂对话。
- 文件阅读 ：能解析 PDF、Word、Excel、PPT、TXT 等文件，帮助你提取和分析信息。
- 丰富知识库：覆盖科技、历史、金融、娱乐等多个领域，提供专业且准确的回答。
- 中文优化：对中文理解和生成特别优化，交流更自然流畅。
无论是写作灵感、代码调试、学习辅导，还是闲聊放松，我都可以陪你！最近过得怎么样？有什么我可以帮你的吗？ 😃
2.2 Agents SDK安装与调用
Agents SDK作为一个工业级的Multi-Agent开发框架，实际使用过程中有非常多的的技术细节，但如果希望快速测试一些功能，则只需要导入Agent和Runner两个模块即可快速运行。其中Agent就是一个Multi-Agent系统中最小执行单元，而Runner则是运行一次次任务的调度函数。但是需要注意的是，由于Agents SDK默认支持的模型是OpenAI的GPT系列模型，因此在修改底层模型的时候，还需要额外导入AsyncOpenAI、OpenAIChatCompletionsModel和ModelSettings等模块。
-
安装Agents SDK依赖
bashpip install openai-agents -
Agents SDK简单调用
bashfrom openai import AsyncOpenAI from agents import OpenAIChatCompletionsModel,Agent,Runner,set_default_openai_client from agents.model_settings import ModelSettings OPENAI_API_KEY="hk-xxx" OPENAI_API_BASE="https://api.openai-hk.com/v1" MODEL="deepseek-v3" # 创建一个Agent对象并调用DeepSeek模型 external_client = AsyncOpenAI( base_url =OPENAI_API_BASE, api_key=OPENAI_API_KEY, ) set_default_openai_client(external_client) deepseek_model = OpenAIChatCompletionsModel( model=MODEL, openai_client=external_client) # ame就是Agent的名称，而instructions就是Agent的"系统提示" agent = Agent(name="Assistant", instructions="你是一名助人为乐的助手。", model=deepseek_model) result = await Runner.run(agent, "请写一首关于编程中递归的俳句。") print(result.final_output)
三 构造多轮对话机器人
3.1 具体响应结果特点
-
不同于传统的
chat.completion API是Messages驱动（传入Message、传出Message），Agents SDK是事件驱动，Agents SDK会将整个运行过程看成是一次次的事件。例如上述创建完俳（pái）句后，全部的事件都保留在result中。pythonresultjs{ RunResult(input='请写一首关于编程中递归的俳句。', new_items=[ MessageOutputItem(agent=Agent(name='Assistant', handoff_description=None, tools=[ ], mcp_servers=[ ], mcp_config={ }, instructions='你是一名助人为乐的助手。', prompt=None, handoffs=[ ], model=<agents.models.openai_chatcompletions.OpenAIChatCompletionsModelobjectat0x000001787D93B4D0>, model_settings=ModelSettings(temperature=None, top_p=None, frequency_penalty=None, presence_penalty=None, tool_choice=None, parallel_tool_calls=None, truncation=None, max_tokens=None, reasoning=None, metadata=None, store=None, include_usage=None, response_include=None, extra_query=None, extra_body=None, extra_headers=None, extra_args=None), input_guardrails=[ ], output_guardrails=[ ], output_type=None, hooks=None, tool_use_behavior='run_llm_again', reset_tool_choice=True), raw_item=ResponseOutputMessage(id='__fake_id__', content=[ ResponseOutputText(annotations=[ ], text='函数自调用，\n层层深入栈中游，\n终有归来时。', type='output_text') ], role='assistant', status='completed', type='message'), type='message_output_item') ], raw_responses=[ ModelResponse(output=[ ResponseOutputMessage(id='__fake_id__', content=[ ResponseOutputText(annotations=[ ], text='函数自调用，\n层层深入栈中游，\n终有归来时。', type='output_text') ], role='assistant', status='completed', type='message') ], usage=Usage(requests=1, input_tokens=22, input_tokens_details=InputTokensDetails(cached_tokens=0), output_tokens=17, output_tokens_details=OutputTokensDetails(reasoning_tokens=0), total_tokens=39), response_id=None) ], final_output='函数自调用，\n层层深入栈中游，\n终有归来时。', input_guardrail_results=[ ], output_guardrail_results=[ ], context_wrapper=RunContextWrapper(context=None, usage=Usage(requests=1, input_tokens=22, input_tokens_details=InputTokensDetails(cached_tokens=0), output_tokens=17, output_tokens_details=OutputTokensDetails(reasoning_tokens=0), total_tokens=39)), _last_agent=Agent(name='Assistant', handoff_description=None, tools=[ ], mcp_servers=[ ], mcp_config={ }, instructions='你是一名助人为乐的助手。', prompt=None, handoffs=[ ], model=<agents.models.openai_chatcompletions.OpenAIChatCompletionsModelobjectat0x000001787D93B4D0>, model_settings=ModelSettings(temperature=None, top_p=None, frequency_penalty=None, presence_penalty=None, tool_choice=None, parallel_tool_calls=None, truncation=None, max_tokens=None, reasoning=None, metadata=None, store=None, include_usage=None, response_include=None, extra_query=None, extra_body=None, extra_headers=None, extra_args=None), input_guardrails=[ ], output_guardrails=[ ], output_type=None, hooks=None, tool_use_behavior='run_llm_again', reset_tool_choice=True)) } -
通过
new_items属性来查看全部的事件，全部事件用一个列表进行表示。bashresult.new_items
js
{
[
MessageOutputItem(agent=Agent(name='Assistant',
handoff_description=None,
tools=[ ],
mcp_servers=[],
mcp_config={},
instructions='你是一名助人为乐的助手。',
prompt=None,
handoffs=[],
model=<agents.models.openai_chatcompletions.OpenAIChatCompletionsModelobjectat0x000001787D93B4D0>,
model_settings=ModelSettings(temperature=None,
top_p=None,
frequency_penalty=None,
presence_penalty=None,
tool_choice=None,
parallel_tool_calls=None,
truncation=None,
max_tokens=None,
reasoning=None,
metadata=None,
store=None,
include_usage=None,
response_include=None,
extra_query=None,
extra_body=None,
extra_headers=None,
extra_args=None),
input_guardrails=[],
output_guardrails=[],
output_type=None,
hooks=None,
tool_use_behavior='run_llm_again',
reset_tool_choice=True),
raw_item=ResponseOutputMessage(id='__fake_id__',
content=[
ResponseOutputText(annotations=[],
text='函数自调用，\n层层深入栈中游，\n终有归来时。',
type='output_text')
],
role='assistant',
status='completed',
type='message'),
type='message_output_item')
]
}-
可以发现列表中只有一个事件，可以通过
len(result.new_items)进行验证，即是一次MessageOutputItem，也就是消息创建事件（也就是大模型发生一次回复）。pythontype(result.new_items[0])bashagents.items.MessageOutputItem -
具体回复的内容，则可以通过
raw_item来查看result.new_items[0].raw_itembashResponseOutputMessage(id='__fake_id__', content=[ResponseOutputText(annotations=[], text='函数自调用， \n层层深入栈中游， \n终有归来时。', type='output_text')], role='assistant', status='completed', type='message') -
Agents SDK为了方便我们快速构造多轮对话机器人，专门提供了一个
to_input_list()方法，可以直接将用户的输入和本次输出结果拼接成一个消息列表。bashresult.to_input_list()json[{'content': '请写一首关于编程中递归的俳句。', 'role': 'user'}, {'id': '__fake_id__', 'content': [{'annotations': [], 'text': '函数自调用， \n层层深入栈中游， \n终有归来时。', 'type': 'output_text'}], 'role': 'assistant', 'status': 'completed', 'type': 'message'}]
-
验证消息列表记忆
bashmessages = result.to_input_list() messages.append({"role": "user", "content":"请问我的上一个问题是什么？"}) print(messages) result = await Runner.run(agent, messages) print(result.final_output) print(result.to_input_list())
bash
[{'content': '请写一首关于编程中递归的俳句。', 'role': 'user'}, {'id': '__fake_id__', 'content': [{'annotations': [], 'text': '函数自调用， \n层层深入栈中游， \n终有归来时。', 'type': 'output_text'}], 'role': 'assistant', 'status': 'completed', 'type': 'message'}, {'role': 'user', 'content': '请问我的上一个问题是什么？'}]
你上一个问题是：
**"请写一首关于编程中递归的俳句。"**
需要调整或补充回答吗？还是想继续探讨递归或俳句？ 😊
[{'content': '请写一首关于编程中递归的俳句。', 'role': 'user'}, {'id': '__fake_id__', 'content': [{'annotations': [], 'text': '函数自调用， \n层层深入栈中游， \n终有归来时。', 'type': 'output_text'}], 'role': 'assistant', 'status': 'completed', 'type': 'message'}, {'role': 'user', 'content': '请问我的上一个问题是什么？'}, {'id': '__fake_id__', 'content': [{'annotations': [], 'text': '你上一个问题是： \n**"请写一首关于编程中递归的俳句。"** \n\n需要调整或补充回答吗？还是想继续探讨递归或俳句？ 😊', 'type': 'output_text'}], 'role': 'assistant', 'status': 'completed', 'type': 'message'}]3.2 多轮对话完整代码
python
from openai import AsyncOpenAI
from agents import OpenAIChatCompletionsModel,Agent,Runner,set_default_openai_client
from agents.model_settings import ModelSettings
from IPython.display import display, Code, Markdown, Image
OPENAI_API_KEY="hk-xxx"
OPENAI_API_BASE="https://api.openai-hk.com/v1"
MODEL="deepseek-v3"
# 创建一个Agent对象并调用DeepSeek模型
external_client = AsyncOpenAI(
base_url =OPENAI_API_BASE,
api_key=OPENAI_API_KEY,
)
set_default_openai_client(external_client)
deepseek_model = OpenAIChatCompletionsModel(
model=MODEL,
openai_client=external_client)
# ame就是Agent的名称，而instructions就是Agent的"系统提示"
agent = Agent(name="Assistant",
instructions="你是一名助人为乐的助手。",
model=deepseek_model)
async def chat(Agent):
input_items = []
while True:
user_input = input("💬 请输入你的消息（输入quit/exit退出）：")
if user_input.lower() in ["exit", "quit"]:
print("✅ 对话已结束")
break
# 主动添加询问消息
input_items.append({"content": user_input, "role": "user"})
# 自动添加事件中的回答消息
result = await Runner.run(Agent, input_items)
display(Markdown(result.final_output))
input_items = result.to_input_list()
await chat(agent)3.3 多轮对话内容
💬 请输入你的消息（输入quit/exit退出）： 你好，你可以帮助我吗/
当然可以！我很乐意帮助你。请告诉我你需要什么帮助，无论是学习、工作、生活问题，还是其他任何疑问，我都会尽力为你解答。😊
你可以直接在这里描述你的问题或需求，我会尽快给你最实用的建议或信息！
💬 请输入你的消息（输入quit/exit退出）： 我想赶紧研究生毕业，给我两条建议
当然！如果你想加速研究生毕业，以下是两条最核心的建议，结合效率和可行性：
- 明确毕业条件，优先完成"硬指标"
研究进度：快速锁定导师认可的毕业课题（避免中途换题），集中精力完成论文核心章节（如实验/数据分析），其他部分（如文献综述）可后期补充。
发表要求：如果学校要求发表论文，优先投递周期短的期刊/会议（如EI会议、校定核心期刊），或与导师协商用项目报告、专利等替代部分要求。 - 高效时间管理 + 主动沟通
制定极简计划：将任务拆解到周，例如：
第1-3个月：完成实验或建模；
第4-5个月：写论文+投稿；
第6个月：修改/准备答辩。
高频同步导师：每周固定时间汇报进展（哪怕只有一点），让导师看到你的主动性，避免后期因反馈延迟耽误时间。
额外提示：如果时间紧迫，可申请提前答辩（需提前查清学校政策），或利用课题组已有数据/合作项目减少工作量。
如果需要具体某方面的技巧（比如如何快速写论文、应对导师拖延），可以告诉我，我再展开细说！ 💪
💬 请输入你的消息（输入quit/exit退出）： 我上一个问题是什么来着？
你上一个问题是："我想赶紧研究生毕业，给我两条建议"
我回复了两条核心建议（明确毕业条件 + 高效时间管理），并附带了额外提示。需要我复述具体内容，或补充其他方面吗？ 😊（小提醒：如果想回顾之前的对话，可以随时告诉我~）
💬 请输入你的消息（输入quit/exit退出）： quit
✅ 对话已结束
四 接入ollama/vLLM本地模型
- 接入本地模型测试
python
from openai import OpenAI
client = OpenAI(
base_url='http://localhost:11434/v1/',
api_key='ollama', # required but ignored
)
prompt = "你好，好久不见！"
messages = [
{"role": "user", "content": prompt}
]
response = client.chat.completions.create(
messages=messages,
model='deepseek-r1:14b',
)
print(response.choices[0].message.content)- 接入Agent SDK测试
python
from openai import AsyncOpenAI
from agents import OpenAIChatCompletionsModel,Agent,Runner,set_default_openai_client
from agents import set_tracing_disabled # or from your framework's module
external_client = AsyncOpenAI(
base_url = 'http://localhost:11434/v1',
api_key='ollama',
)
set_default_openai_client(external_client)
set_tracing_disabled(True)
agent = Agent(name="Assistant",
instructions="你是一名助人为乐的助手。",
model=OpenAIChatCompletionsModel(
model="deepseek-r1:14b",
openai_client=external_client,
))
result = await Runner.run(agent, "请写一首关于编程中递归的诗句。")
print(result.final_output)嗯，用户让我写一首关于编程中递归的诗句。首先，我得理解什么是递归。递归是一种函数调用自身的方法，在解决问题时会将问题分解为更小的子问题。 接下来，我要把递归的特点融入诗句里。递归通常涉及重复执行和逐步缩小的问题规模。所以，我想用一些自然现象或者循环的概念来比喻。 考虑到诗的韵律和意象，我想到阶梯和螺旋这两个形象。阶梯代表逐步分解问题，而螺旋则象征不断深入的过程。这样可以很好地表现出递归的特点。 然后，我需要找出押韵的词汇，让诗句更流畅。第一句"函数清点阶与梯"用了"梯"，有押韵的感觉。第二句"调用自身旋入迷"中的"迷"对仗也不错，同时表达了深入的过程。 第三和第四句需要总结递归带来的结果。"数层深意终自现"说明通过多次调用，问题的深层含义逐渐显现。最后一句"解法重生始Adjacent（相邻）"暗示了在重复过程中，新的解法出现，类似于函数调用时的状态变化。 整体来看，这样的诗句既贴合递归的概念，又有诗意和韵律感。希望用户能够通过这首诗更好地理解和记忆递归的特点。
函数清点阶与梯，
调用自身旋入迷。
数层深意终自现，
解法重生始Adjacent（相邻）。