For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

智能体 API

智能体 SDK

ChatKit

API Dashboard
试用 ChatGPT

配置智能体

定义智能体、复用其配置，并自定义每个会话。

智能体配置定义了智能体的行为方式。您可以在创建会话时提供配置，也可以将其保存以供复用。会话保存对话和工作内容，已保存的智能体则保存可复用的设置。

定义智能体的行为

先设置模型和指令，再添加任务所需的工具和控制项：

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

创建会话时，通过 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 连接；有关任务委派，请参阅多智能体。

在多个会话中复用智能体

保存智能体，即可在多个会话中复用其配置。只需创建一次，然后在启动每个会话时，将其 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 会替换已保存的工具列表。

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

更新现有会话的设置

发送包含 agent 对象的 POST /v1/agents/sessions/{session_id} 请求，即可更改单个会话的 model、reasoning.effort 或 service_tier。beta 和 GA 版 API 均支持这些设置。您可以在同一请求中更新 metadata。

更改仅适用于更新完成后发送的消息所启动的新轮次。已发送但尚未处理完成的消息可能仍使用原有设置。正在进行的轮次会保留其设置，即使您发送引导消息也不例外。会话会保留其对话历史记录。所选模型必须支持更新后的设置，否则更新会失败。

  • agent 和 reasoning 对象会将提供的字段合并到当前设置中。未提供的字段保持不变，包括推理摘要。仅更改 model 会保留会话的推理强度和服务层级。
  • reasoning.effort: null 会将推理强度重置为所选模型的默认值。
  • service_tier: null 会恢复自动选择服务层级。
  • 必须始终设置模型，因此您不能提供 model: null。agent 和 reasoning 对象也不接受 null。
  • metadata 会替换整个映射。省略该字段可保留元数据，传入 null 或 {} 则可将其清空。

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

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

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

您无法通过此端点更新 reasoning.summary、text、tools、instructions 或 multi_agent。要更改这些设置，请创建新会话。

环境设置

创建会话时，除 agent 外，还需设置 environment，以确定智能体运行命令和处理文件的环境。

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

对于 OpenAI 托管的环境，请配置任务所需的软件包、初始文件和网络访问。您可以在多个会话中复用环境模板。对于自托管环境，请准备好计算资源并连接执行器。

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