智能代理新范式：OpenAI Responses API

智能代理新范式OpenAI Responses API

OpenAI Agents SDK 的推出，为开发者构建智能代理（Agents）工作流提供了强大而轻量级的框架。在其核心，Responses API 作为 OpenAI 为智能代理量身打造的全新基础构件，正引领着 AI 交互的未来。它巧妙地融合了 Chat Completions API 的简洁易用性与 Assistants API 内置工具的强大能力，使得代理能够以前所未有的智能和效率执行复杂任务。

本文将带您深入了解 Responses API 的核心功能、如何通过它生成文本、控制消息流，以及最令人兴奋的——如何利用其集成的各种强大工具，构建真正智能化的应用。

Responses API 核心概览

Responses API 旨在成为 OpenAI 代理系统的核心 API，它不仅继承了传统文本生成 API 的简洁性，更在功能上进行了大幅增强。

核心特点:

  • 简洁易用：保留了 Chat Completions API 的直观性。
  • 增强功能：内置支持函数调用（Function Calling）、Web 搜索、文件搜索、计算机控制等一系列强大的工具。
  • 专为代理设计：特别适用于构建能够智能化执行任务的代理系统。
  • 未来发展核心：它将结合 Agents SDK，提供更灵活的任务编排能力。

1. 文本生成与消息控制

使用 Responses API 生成文本与 ChatGPT 的工作方式类似，通过一个简单的提示词即可让模型生成所需内容。

生成文本示例

要生成文本，只需指定模型并提供输入：

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o", # 指定使用 GPT-4o 模型
    input="写一个关于编程中递归的五行俳句。"
)
print(response.output_text)

示例输出:

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

关键点：response.output_text 直接包含了模型生成的文本。API 响应的 output 数组可能包含多个结果，而 output_text 属性方便您直接获取所有文本输出。除了纯文本，模型也可以返回 JSON 结构化数据（称为 Structured Outputs）。

消息角色与指令控制

Responses API 提供了灵活的方式来控制模型的行为，主要通过 instructions 参数和 input 数组中的不同消息角色。

  1. instructions 参数（全局指令，优先级最高）：
    此参数用于提供模型的全局行为指令，例如语气、目标等。其权重最高，会影响模型的所有后续响应。

    from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    instructions="说话像个海盗。", # 在 instructions 中定义“说话像海盗”
    input="JavaScript 中分号是可选的吗？",
)
print(response.output_text)

    示例输出:

    Arrr, matey! In JavaScript, semicolons be often optional, but beware, for they
help avoid nasty parse errors!

  2. input 数组指定不同角色（多轮对话）：
    您可以在 input 数组中指定不同角色的消息，包括 developer、user 和 assistant。

    消息角色的优先级:

    • developer：最高优先级，由开发者提供的指令，类似于 system 角色。
    • user：次高优先级，由最终用户提供的输入。
    • assistant：最低优先级，由模型生成的响应。
    from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    input=[
        {
            "role": "developer",
            "content": "说话像个海盗。" # developer 角色作为系统设定
        },
        {
            "role": "user",
            "content": "JavaScript 中分号是可选的吗？" # 用户输入
        }
    ]
)
print(response.output_text)

    注意：多轮对话中，管理对话状态是关键。

选择合适的模型

选择合适的模型对性能和成本至关重要。OpenAI 提供了多种模型，各具特点:

  • 推理（Reasoning）模型：

    • 特点：内部进行复杂思维链分析，适用于逻辑推理、分步计划等任务。
    • 优缺点：理解复杂任务、逻辑清晰；但速度较慢、成本更高。
    • 适用场景：复杂分析、多步推理、研究类任务。

  • GPT（通用）模型：

    • 特点：快速、经济、高效，但需要更明确的指令来引导任务。
    • 优缺点：生成速度快、性价比高；可能不擅长复杂的推理任务。
    • 适用场景：快速文本生成、聊天机器人、常规任务。

  • 规模大小选择:

    • 大型模型（GPT-4o）：理解能力强，泛化能力好，适用于复杂问题。
    • 小型模型（GPT-4o Mini）：更快、更便宜，适合特定任务，可通过微调优化。

结论：如果不确定，GPT-4o 是智能性、速度和成本的最佳平衡点。

提示词工程 vs. 微调

提示词工程（Prompt Engineering） 是优化模型输出的关键，通过详细说明、示例驱动、目标导向描述、测试与迭代来提升效果。

如果提示词工程仍无法满足需求，可以考虑：

  • 微调（Fine-tuning）：针对特定任务调整模型权重，提升准确性。适用于需要定制化模型、固定风格、严格遵循复杂指令等场景。
  • 蒸馏（Distillation）：用大模型生成的数据来优化小模型的表现。

通常情况下，调整提示词即可满足需求。

2. Responses API 的新特性：强大的内置工具集成

Responses API 的最大亮点在于其增强的功能，能够支持多种内置工具，使得代理具备了与外部世界交互的能力。

Web 搜索功能允许模型在生成回答之前查询最新的信息，类似于 ChatGPT 的搜索功能，并提供清晰的引用来源。

启用 Web 搜索:
将 web_search_preview 添加到 tools 数组即可。模型会自行决定是否使用该工具。

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "web_search_preview"}], # 启用 Web 搜索工具
    input="今天有什么积极的新闻？"
)
print(response.output_text)

强制使用 Web 搜索:
如果希望模型强制使用 Web 搜索，可以设置 tool_choice 参数。

# 让 Web 搜索始终执行
tool_choice={"type": "web_search_preview"}

这会提升一致性，但可能会增加查询时间.

输出格式与引用:
模型调用 Web 搜索后，API 响应将包含 web_search_call（搜索请求 ID 和状态）和 message（模型回答，带有 url_citation 引用信息，包括 URL、标题和在文本中的位置）。

定制用户位置:
Web 搜索可以根据用户的位置优化搜索结果，您可以指定 country、city、region 和 timezone。

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "web_search_preview",
        "user_location": {
            "type": "approximate",
            "country": "GB", # 指定国家为英国
            "city": "London", # 指定城市为伦敦
            "region": "London",
        }
    }],
    input="Granary Square 附近最好的餐厅有哪些？",
)
print(response.output_text)

搜索上下文大小:
search_context_size 控制从 Web 获取的上下文信息量，可选值包括 high、medium（默认）和 low，影响成本、质量和响应速度。

文件搜索工具允许模型在已上传的文件知识库（vector stores） 中进行语义搜索和关键词搜索，从而扩展模型的内在知识。

特点:

  • 托管工具：由 OpenAI 负责管理，无需用户自行实现搜索逻辑。
  • 自动调用：模型决定何时使用该工具进行检索。
  • 向量存储支持：通过创建向量存储并上传文件来增强模型的知识。

使用文件搜索:

  1. 创建向量存储。
  2. 上传文件到向量存储。
  3. 在 API 调用中启用 file_search，并指定向量存储 ID。

注意：目前一次搜索仅支持一个向量存储。

启用文件搜索示例:

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o-mini",
    input="OpenAI 的深度研究是什么？",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["<vector_store_id>"] # 指定要搜索的向量存储 ID
    }]
)
print(response)

模型会自动决定是否调用文件搜索。

API 响应结构:
响应包含 file_search_call（搜索请求 ID、状态和查询内容）和 message（模型回答，带有 file_citation 引用信息，包括 file_id 和 filename）。

检索结果定制:
您可以自定义搜索行为，优化结果质量、成本和响应速度。

  • 限制搜索结果数量：使用 max_num_results 减少 token 使用量，提高查询速度。
    "max_num_results": 2 # 限制搜索返回的文件数量
  • 包含搜索结果：默认情况下不直接包含原始搜索结果，可设置 include 参数获取。
    include=["output[*].file_search_call.search_results"] # 包含搜索结果
  • 过滤文件元数据：通过 filters 按照文件类型等元数据筛选搜索结果。
    "filters": {
    "type": "eq",    # 等于
    "key": "type",   # 过滤字段
    "value": "blog"  # 只搜索博客
}

支持的文件格式: 包括 .pdf, .docx, .json, .py, .txt 等文本、代码和 JSON/XML 文件，以及 .png, .jpeg 等图片格式。文件必须使用 utf-8、utf-16 或 ascii 编码。

限制: 项目级别最多 100GB 文件，向量存储最多 10,000 个文件，单个文件最大 512MB。

C. 计算机使用（Computer Use, CUA）

计算机使用代理（CUA） 允许模型模拟人在计算机上操作，例如点击、输入、滚动等，从而执行自动化任务。它结合了 GPT-4o 的视觉能力（识别屏幕截图）和高级推理能力（模拟计算机界面交互）。

特点:

  • 允许模型执行计算机操作（点击、输入文本、滚动页面）。
  • 通过截图感知界面变化，并决定下一步操作。
  • 可用于网页浏览、数据输入、在线购物、表单填写等任务。
  • 目前是 Beta 版，不适用于高安全性任务。

工作原理:
CUA 的执行流程是一个循环：

  1. 发送请求：用户提供目标任务，并可选地传入初始界面截图。
  2. 接收响应：模型返回 computer_call（操作指令）、reasoning 或 safety_check。
  3. 执行操作：您的应用程序解析指令并模拟操作。
  4. 获取更新状态：执行操作后，截图当前界面并传回模型。
  5. 重复，直到任务完成。

发送请求示例:

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="computer-use-preview",
    tools=[{
        "type": "computer_use_preview",
        "display_width": 1024,
        "display_height": 768,
        "environment": "browser" # 其他选项："mac", "windows", "ubuntu"
    }],
    input=[
        {
            "role": "user",
            "content": "在 bing.com 上查看 OpenAI 最新新闻。"
        }
    ],
    truncation="auto" # 允许截断
)
print(response.output)

支持的操作类型:
click(x, y)、scroll(x, y, scroll_x, scroll_y)、keypress(keys)、type(text)、wait()、screenshot()。

执行循环示例:
CUA 的强大之处在于其循环执行能力。应用程序负责解析 computer_call、执行操作、获取最新截图并反馈给模型，从而实现自动化任务流。

import time
import base64
from openai import OpenAI
# 假设 handle_model_action 和 get_screenshot 已经定义并能处理 Playwright 操作

client = OpenAI()

def computer_use_loop(instance, response):
    while True:
        computer_calls = [item for item in response.output if item.type == "computer_call"]
        if not computer_calls:
            print("无计算机调用，任务完成。模型输出:")
            for item in response.output:
                print(item)
            break # 退出循环

        computer_call = computer_calls
        last_call_id = computer_call.call_id
        action = computer_call.action

        # 执行操作
        handle_model_action(instance, action) # 示例函数，需自行实现
        time.sleep(1) # 等待操作完成

        # 获取截图
        screenshot_bytes = get_screenshot(instance) # 示例函数，需自行实现
        screenshot_base64 = base64.b64encode(screenshot_bytes).decode("utf-8")

        # 发送截图回模型
        response = client.responses.create(
            model="computer-use-preview",
            previous_response_id=response.id,
            tools=[
                {
                    "type": "computer_use_preview",
                    "display_width": 1024,
                    "display_height": 768,
                    "environment": "browser"
                }
            ],
            input=[
                {
                    "call_id": last_call_id,
                    "type": "computer_call_output",
                    "output": {
                        "type": "input_image",
                        "image_url": f"data:image/png;base64,{screenshot_base64}"
                    }
                }
            ],
            truncation="auto"
        )
    return response

# 调用示例：
# from playwright.sync_api import sync_playwright
# with sync_playwright() as p:
#     browser = p.chromium.launch()
#     page = browser.new_page()
#     # 假设首次请求
#     initial_response = client.responses.create(
#         model="computer-use-preview",
#         tools=[{"type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser"}],
#         input=[{"role": "user", "content": "打开 bing.com"}],
#         truncation="auto"
#     )
#     computer_use_loop(page, initial_response)
#     browser.close()

安全检查: CUA 可能会返回 pending_safety_checks，以避免执行风险操作（如恶意指令、访问敏感域）。您需要确认并手动执行检查。

D. 代码解释器（Code Interpreter）

代码解释器允许 OpenAI Assistants 代理运行 Python 代码，用于数学计算、数据处理、文件操作、绘图等。

特点:

  • 执行 Python 代码：助手可编写并迭代运行 Python 代码，直到任务完成。
  • 支持文件处理：可读取 .csv, .json, .pdf 等多种格式文件。
  • 生成文件：可输出图像、数据文件（如 .csv）、PDF 等，并提供下载链接。
  • 自动修复错误：如果代码运行失败，助手会迭代修改代码，直到成功执行。
  • 定价：$0.03 / 会话（每个会话默认持续 1 小时），同一线程内的多个用户调用共享会话，降低成本。

启用代码解释器:
在 tools 参数中启用 code_interpreter 即可。

from openai import OpenAI

client = OpenAI()
assistant = client.beta.assistants.create( # 示例创建助手
    instructions="你是一个数学导师。请使用 Python 代码计算答案。",
    model="gpt-4o",
    tools=[{"type": "code_interpreter"}] # 启用代码解释器
)
# 该助手在遇到数学问题时，会自动决定是否运行 Python 代码进行计算

传递文件给代码解释器:
代码解释器可以读取文件，进行数据处理和分析。支持：

  • 全局文件（Assistant 级）：所有对话共享。
  • 局部文件（Thread 级）：仅当前对话可用。

代码执行与日志:
您可以通过 API 列出代码执行日志，查看助手运行的 Python 代码和执行结果。

读取 & 下载代码生成的文件:
代码解释器可生成文件（如 CSV、图像、PDF），您可以通过其文件 ID 下载它们。

求解方程示例:
代码解释器会自动运行 Python 代码来解决复杂问题。

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "code_interpreter"}],
    input="请用 Python 计算 `3x + 11 = 14` 的解。",
)
print(response.output_text)

输出:

x = 1

支持的文件类型:
包括 .csv, .json, .pdf, .xlsx, .png, .jpeg, .zip, .tar 等。最大文件大小为 512 MB。

关键特性总结:

  • ✅ 自动 Python 代码执行
  • ✅ 支持文件读取 & 生成（CSV, PDF, 图像等）
  • ✅ 错误自动修复 & 代码迭代优化
  • ✅ 代码执行日志可追踪
  • ✅ 多种 API 调用方式（Assistant 级 & Thread 级）
  • ✅ 定价合理（$0.03 / 小时）

3. 构建高效、可靠的智能代理

OpenAI Agents SDK 提供了一个轻量级但功能强大的框架，用于构建多智能体工作流。结合 Responses API 及其内置工具，您可以构建出高效、可靠的智能代理。

核心组件:

  • 模型（Models）：核心智能体，负责推理、决策、处理多模态数据（如 GPT-4o, GPT-4o-mini）。
  • 工具（Tools）：代理与环境交互的接口，包括函数调用、Web 搜索、文件搜索、计算机控制。
  • 知识 & 记忆（Knowledge & Memory）：使代理可以访问外部知识并持久存储信息（如向量存储、文件搜索、嵌入模型）。
  • 安全防护（Guardrails）：防止不相关、有害或不良行为（如 Moderation API, 指令层级）。
  • 编排（Orchestration）：代理的开发、部署、监控和改进（通过 Agents SDK, Tracing, Evaluations, Fine-tuning）。

总结

OpenAI Responses API 作为智能代理系统的核心基础构件，通过其简洁的文本生成能力和强大的内置工具集成（Web 搜索、文件搜索、计算机使用、代码解释器），为开发者构建下一代智能化应用提供了前所未有的灵活性和能力。无论是需要获取实时信息、处理私有文档，还是模拟计算机操作，Responses API 都能让您的代理变得更加智能和高效。拥抱 Responses API，开启您智能代理的无限可能！

posted @ 2025-06-27 19:27  SIo_2  阅读(93)  评论(0)    收藏  举报