如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

配置智能体

定义智能体,复用其配置,并为每个会话自定义设置。

智能体配置决定智能体的行为。您可以在创建会话时提供配置,也可以将其保存以供复用。对话和任务执行都在会话中进行,已保存的智能体则保留可复用的设置。

定义智能体的行为

先指定模型和指令,再根据任务需要添加工具和控制项:

  • 模型: 指定由哪个模型执行任务。
  • 指令: 说明智能体应做什么,以及应如何行动。
  • 工具: 指定智能体可以执行哪些操作,例如搜索网页或调用您的函数。
  • 推理和输出: 设置模型的推理强度,以及回复的格式和详细程度。

创建会话时,通过 agent 传入这些设置。以下示例指定了模型和指令,并提供了第一条用户消息:

为单个会话配置智能体
from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer the user clearly and concisely.",
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "What can you help with?"}],
        }
    ],
)
print(session.to_json())

有关配置字段及其取值,请参阅 Agents API 参考。有关设置步骤,请参阅函数、计算机使用、MCP 连接或多智能体任务委派。

配置大小

请确保指令和工具配置的总大小小于 4 MiB(4,194,304 字节),为 Agents API 元数据预留少量空间。如果配置过大导致会话启动失败,请缩短指令、精简工具配置,然后创建新会话。

上传到环境的文件受单独的文件限制约束。

跨会话复用智能体

保存智能体后,您可以在多个会话中复用其配置。只需创建一次智能体,然后在每次启动会话时将其 ID 作为 agent_id 传入:

复用智能体
from openai import OpenAI

client = OpenAI()
agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
    timeout=360,
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())

每个会话都有独立的对话,并独立执行任务。要列出、检索、更新或删除已保存的智能体,请参阅 Agents API 参考。凭据存储在凭据库中,与已保存的配置分开存放。

更新已保存的智能体

对已保存智能体的更新仅对新会话生效。每个会话在创建时都会复制已保存的配置,并在后续轮次中沿用这些设置。要更改现有会话,请更新该会话的设置。

更新已保存的智能体时:

  • 省略的字段保留已保存的值。如果只更改 model,则会保留 reasoning、service_tier 和 text。
  • 传入的对象会替换整个字段。如果传入的 reasoning 只包含 effort,已保存的 summary 也会被清除。
  • null 可重置接受该值的字段。例如,reasoning: null 会恢复模型的默认推理强度。

如果新模型不支持某些设置,请在同一请求中更改或重置这些设置。

为单个会话覆盖设置

创建会话时,同时传入 agent_id 和 agent 即可为该会话自定义已保存智能体的配置。对于省略的设置(包括模型),会话会在创建时从已保存的智能体复制相应值。

运行以下示例前,请将示例值 agent_123 替换为已保存智能体的 ID:

为单个会话覆盖智能体配置
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

agent_id = "agent_123"
session = client.beta.agents.sessions.create(
    agent_id=agent_id,
    agent={"instructions": "Answer this question in one concise paragraph."},
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain how an agent connects to an MCP server.",
                }
            ],
        }
    ],
)
print(session.to_json())

覆盖设置仅对该会话生效,不会更改已保存的智能体或其他会话。传入的对象和数组会替换整个字段,不会与已保存的值合并。例如,传入 tools 会替换已保存的工具列表。

有关请求字段,请参阅创建会话 API 参考。

更新现有会话的设置

发送 POST /v1/agents/sessions/{session_id} 请求,并在请求中传入 agent 对象,即可更改单个会话的 tools、model、reasoning.effort 或 service_tier。测试版和正式版 API 均支持这些设置。您还可以在同一请求中更新 metadata。

如果您更改了模型、推理强度或服务层级,更新完成后发送的消息所启动的新轮次会使用相应的新设置。已发送但尚未处理完毕的消息可能仍使用之前的设置。正在进行的轮次会沿用这些设置的原值,即使您在该轮次中发送引导消息也是如此。会话会保留对话历史。所选模型必须支持更新后的设置,否则更新会失败。

  • 对于 agent 和 reasoning 对象,传入的字段会合并到当前设置中。省略的字段(包括推理摘要)保持不变。如果只更改 model,会话会保留当前的推理强度和服务层级。
  • tools 会替换整个工具列表。对函数和 MCP 服务器的更改会在下一次模型调用时生效。对内置工具的更改最迟会在下一轮次生效。省略 tools 可保留当前工具,传入 null 或 [] 可清空工具列表。
  • reasoning.effort: null 会将推理强度重置为所选模型的默认值。
  • service_tier: null 会恢复自动选择服务层级。
  • 会话必须始终指定模型,因此不能传入 model: null。agent 和 reasoning 对象也不接受 null。
  • metadata 会替换整个键值映射。省略该字段可保留元数据,传入 null 或 {} 可将其清空。

例如,以下请求会更改推理强度,并让 API 自动选择服务层级:

{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

更新会话不会更改已保存的智能体或其他会话。之后更新已保存的智能体也不会更改该会话。

您无法通过此端点更新 reasoning.summary、text、instructions 或 multi_agent。要更改这些设置,请创建新会话。有关请求字段,请参阅更新会话 API 参考。

在会话中使用 Daybreak

Agents API 支持 Daybreak Blue 和 Daybreak Red。请使用项目的 API 密钥。该项目必须同时具备访问所选模型及其对应网络安全访问计划的权限。

创建会话时,请在请求体中加入与您的访问计划对应的字段。

Daybreak Blue

{
  "agent": { "model": "gpt-6-sol" },
  "access_programs": { "cyber": "daybreak_blue" }
}

Daybreak Red

{
  "agent": { "model": "gpt-5.6-cyber" },
  "access_programs": { "cyber": "daybreak_red" }
}

自动审核操作请求

将会话级 review 字段设为 "auto_review",即可启用自动审核模式,自动审核支持此功能的审批请求。请将该字段与 agent 或 agent_id 放在同一层级,不要将其放入智能体配置中。创建会话时,如果省略 review,其默认值为 "none"。

自动审核模式也会改变执行权限。启用前,请检查是否满足环境要求。

只有在主任务处于空闲状态且没有正在提交的输入时,才能更新 review。后续执行和恢复操作都会使用新设置。如果在满足这些条件之前请求切换模式,API 会返回 409 Conflict,且不会应用任何更改。请使用已启用自动审核模式的项目和支持该模式的会话。有关如何配置该模式和处理审批请求,请参阅自动审核模式。

环境设置

创建会话时,请将 environment 与 agent 放在同一层级。环境设置决定智能体在哪里运行命令和处理文件。

请选择 none、openai_hosted 或 self_hosted。架构介绍了各选项的适用场景,以及相应环境由谁管理。

对于由 OpenAI 托管的环境,请选择容器大小,并按任务需要配置软件包、初始文件和网络访问权限。您可以在多个会话中复用同一个环境模板。对于自托管环境,请准备好计算资源并连接执行器。

有关环境字段,请参阅创建会话 API 参考。有关技能、插件和模板,请参阅插件。如果您希望在执行结束后保留文件,请参阅会话产物。