Agents-SDK智能体开发[1]之入门

缘友一世2025-08-02 13:33

文章目录

  • 说明
  • [一 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等模块。

  1. 安装Agents SDK依赖

    bash 复制代码 
    pip install openai-agents

  2. Agents SDK简单调用

    bash 复制代码 
    from 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中。

    python 复制代码 
    result
    js 复制代码 
    {
    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属性来查看全部的事件，全部事件用一个列表进行表示。

    bash 复制代码 
    result.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，也就是消息创建事件（也就是大模型发生一次回复）。

    python 复制代码 
    type(result.new_items[0])
    bash 复制代码 
    agents.items.MessageOutputItem

  • 具体回复的内容，则可以通过raw_item来查看result.new_items[0].raw_item

    bash 复制代码 
    ResponseOutputMessage(id='__fake_id__', content=[ResponseOutputText(annotations=[], text='函数自调用，  \n层层深入栈中游，  \n终有归来时。', type='output_text')], role='assistant', status='completed', type='message')

  • Agents SDK为了方便我们快速构造多轮对话机器人，专门提供了一个to_input_list()方法，可以直接将用户的输入和本次输出结果拼接成一个消息列表。

    bash 复制代码 
    result.to_input_list()
    json 复制代码 
    [{'content': '请写一首关于编程中递归的俳句。', 'role': 'user'},
 {'id': '__fake_id__',
  'content': [{'annotations': [],
    'text': '函数自调用，  \n层层深入栈中游，  \n终有归来时。',
    'type': 'output_text'}],
  'role': 'assistant',
  'status': 'completed',
  'type': 'message'}]

  • 验证消息列表记忆

    bash 复制代码 
    messages = 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退出）： 我想赶紧研究生毕业，给我两条建议

当然！如果你想加速研究生毕业，以下是两条最核心的建议，结合效率和可行性：

  1. 明确毕业条件，优先完成"硬指标"
    研究进度：快速锁定导师认可的毕业课题（避免中途换题），集中精力完成论文核心章节（如实验/数据分析），其他部分（如文献综述）可后期补充。
    发表要求：如果学校要求发表论文，优先投递周期短的期刊/会议（如EI会议、校定核心期刊），或与导师协商用项目报告、专利等替代部分要求。
  2. 高效时间管理 + 主动沟通
    制定极简计划：将任务拆解到周，例如：
    第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（相邻）。

相关推荐
CodeShare2 分钟前
某中心将举办机器学习峰会
人工智能·机器学习·数据科学
那就摆吧19 分钟前
U-Net vs. 传统CNN：为什么医学图像分割需要跳过连接？
人工智能·神经网络·cnn·u-net·医学图像
深度学习实战训练营30 分钟前
中英混合的语音识别XPhoneBERT 监督的音频到音素的编码器结合 f0 特征LID
人工智能·音视频·语音识别
WADesk---瓜子38 分钟前
用 AI 自动生成口型同步视频，短视频内容也能一人完成
人工智能·音视频·语音识别·流量运营·用户运营
星环科技TDH社区版1 小时前
AI Agent 的 10 种应用场景：物联网、RAG 与灾难响应
人工智能·物联网
时序之心1 小时前
ICML 2025 | 深度剖析时序 Transformer：为何有效，瓶颈何在？
人工智能·深度学习·transformer
希艾席帝恩1 小时前
拥抱智慧物流时代：数字孪生技术的应用与前景
大数据·人工智能·低代码·数字化转型·业务系统
Bar_artist1 小时前
离线智能破局，架构创新突围：RockAI与中国AI的“另一条车道”
大数据·人工智能
双向331 小时前
高性能MCP服务器架构设计：并发、缓存与监控
人工智能
weixin_464078071 小时前
机器学习sklearn：处理缺失值
人工智能·机器学习·sklearn
热门推荐
01Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code02全球最强模型Grok4，国内已可免费使用！（附教程）03MSPM0G3507——读取引脚的高低电平方法（数字信号循迹模块）04VMware Workstation Pro虚拟机的下载和安装图文保姆级教程(附下载链接)05KGG转MP3工具|非KGM文件|解密音频06腾讯还是太全面了，限时免费！超全CodeBuddy IDE保姆级教程！（附案例）07Coze 开源了，送上保姆级私有化部署方案【建议收藏】082025电赛e题：openmv识别过程丢失矩形09扣子开源本地部署教程 丨Coze智能体小白喂饭级指南102025年电子设计大赛G题《电路模型探究装置》各小问数学推导及个人思路