OpenAI 配置智能体

智能体配置定义智能体如何工作，可以在创建会话时直接提供，也可以保存后复用。会话保留对话与工作，已保存智能体保留可复用设置。

定义智能体行为

从模型和指令开始，再按任务添加工具与控制项：

• 模型：由哪个模型完成工作。
• 指令：智能体要做什么，以及应如何行动。
• 工具：可执行的动作，例如搜索网页或调用应用函数。
• 推理与输出：模型使用多少推理，以及回复的格式和详细程度。

创建会话时，把设置放在 agent 中。以下示例提供模型、指令和第一条用户消息：

来源示例 1（javascript）：

程序文字说明1：清楚、简洁地回答用户。

程序文字说明2：你可以帮助完成哪些事情？

// [中文] 示例 1：定义智能体行为。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import OpenAI from "openai";
const client = new OpenAI();

const session = await 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?",
        },
      ],
    },
  ],
});

console.log(session);

来源示例 2（python）：

沿用程序文字说明1。

沿用程序文字说明2。

## [中文] 示例 2：定义智能体行为。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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())

来源示例 3（go）：

沿用程序文字说明1。

沿用程序文字说明2。

// [中文] 示例 3：定义智能体行为。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
    openai.BetaAgentSessionNewParams{
        Agent: openai.BetaAgentSessionNewParamsAgent{
            Model:        openai.String("gpt-6-astra"),
            Instructions: openai.String("Answer the user clearly and concisely."),
        },
        Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
        Input: openai.BetaAgentSessionNewParamsInputUnion{
            OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
                {
                    Content: []openai.InputContentParamUnion{
                        {
                            OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},
                        },
                    },
                },
            },
        },
    })
if err != nil {
    panic(err)
}
fmt.Println(result)

来源示例 4（java）：

沿用程序文字说明1。

沿用程序文字说明2。

// [中文] 示例 4：定义智能体行为。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions("Answer the user clearly and concisely.")
                        .build())
                .environmentNone()
                .input("What can you help with?")
                .build());
System.out.println(result);

来源示例 5（ruby）：

沿用程序文字说明1。

沿用程序文字说明2。

## [中文] 示例 5：定义智能体行为。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
require "openai"

client = OpenAI::Client.new
result = 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?"
        }
      ]
    }
  ]
)
puts result

配置字段及可选值见 Agents API 参考。专项配置见函数、计算机使用、MCP 连接和多智能体委派。

配置大小

指令与工具配置的合计大小应小于 4 MiB（4,194,304 字节），并为 Agents API 元数据预留少量空间。如果配置过大导致会话无法启动，缩小指令和工具配置后创建新会话。

上传到环境的文件采用单独的文件限制。

跨会话复用智能体

先保存智能体，再在各会话启动时传入其 agent_id，即可复用配置：

来源示例 6（javascript）：

程序文字说明3：准确回答技术问题。

程序文字说明5：解释智能体如何连接MCP服务器。

// [中文] 示例 6：跨会话复用智能体。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import OpenAI from "openai";

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

来源示例 7（python）：

沿用程序文字说明3。

沿用程序文字说明5。

## [中文] 示例 7：跨会话复用智能体。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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())

来源示例 8（go）：

沿用程序文字说明3。

沿用程序文字说明5。

// [中文] 示例 8：跨会话复用智能体。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
agent, err := client.Beta.Agents.New(ctx,
    openai.BetaAgentNewParams{
        Model:        "gpt-6-astra",
        Instructions: openai.String("Answer technical questions accurately."),
        Reasoning:    openai.AgentReasoningParam{Summary: "auto"},
    })
if err != nil {
    panic(err)
}
result, err := client.Beta.Agents.Sessions.New(ctx,
    openai.BetaAgentSessionNewParams{
        AgentID:     openai.String(agent.ID),
        Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
        Input:       openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},
    })
if err != nil {
    panic(err)
}
fmt.Println(result)

来源示例 9（java）：

沿用程序文字说明3。

沿用程序文字说明5。

// [中文] 示例 9：跨会话复用智能体。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentCreateParams;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var agent =
    client
        .beta()
        .agents()
        .create(
            AgentCreateParams.builder()
                .model("gpt-6-astra")
                .instructions("Answer technical questions accurately.")
                .reasoning(
                    AgentReasoningParam.builder()
                        .summary(AgentReasoningParam.Summary.of("auto"))
                        .build())
                .build());
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId(agent.id())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

来源示例 10（ruby）：

沿用程序文字说明3。

沿用程序文字说明5。

## [中文] 示例 10：跨会话复用智能体。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
require "openai"

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

每个会话都有自己的对话与工作。已保存智能体的列出、读取、更新和删除方法见 Agents API 参考。凭证存放在凭证库，与已保存配置分开。

更新已保存的智能体

更新已保存智能体只影响新会话。创建会话时会复制该智能体配置，并在后续轮次沿用。要改变已有会话，需更新现有会话设置。

• 省略的字段保留已保存值。仅更改 model 不会清除 reasoning、service_tier 或 text。
• 提供的对象替换整个字段。例如仅提供含 effort 的 reasoning，也会清除此前保存的 summary。
• 接受 null 的字段可用它重置，例如 reasoning: null 恢复模型默认推理强度。

新模型不支持的设置，应在同一次请求中更改或重置。

为一个会话覆盖设置

创建会话时同时提供 agent_id 与 agent，可为该会话定制已保存配置。省略的设置，包括模型，会在创建时从已保存智能体复制。

运行示例前，将示意值 agent_123 换为已保存智能体的实际 ID：

来源示例 11（javascript）：

程序文字说明4：用一个简洁段落回答此问题。

沿用程序文字说明5。

// [中文] 示例 11：为一个会话覆盖设置。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const agentId = "agent_123";
const session = await client.beta.agents.sessions.create({
  agent_id: agentId,
  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.",
        },
      ],
    },
  ],
});

console.log(session);

来源示例 12（python）：

沿用程序文字说明4。

沿用程序文字说明5。

## [中文] 示例 12：为一个会话覆盖设置。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
## 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())

来源示例 13（go）：

沿用程序文字说明4。

沿用程序文字说明5。

// [中文] 示例 13：为一个会话覆盖设置。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
// Replace the illustrative IDs and URLs below with your own resource values.
import (
    "context"
    "fmt"

    "github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
    openai.BetaAgentSessionNewParams{
        AgentID:     openai.String("agent_123"),
        Agent:       openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},
        Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
        Input: openai.BetaAgentSessionNewParamsInputUnion{
            OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
                {
                    Content: []openai.InputContentParamUnion{
                        {
                            OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},
                        },
                    },
                },
            },
        },
    })
if err != nil {
    panic(err)
}
fmt.Println(result)

来源示例 14（java）：

沿用程序文字说明4。

沿用程序文字说明5。

// [中文] 示例 14：为一个会话覆盖设置。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
// Replace the illustrative IDs and URLs below with your own resource values.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId("agent_123")
                .agent(
                    SessionCreateParams.Agent.builder()
                        .instructions("Answer this question in one concise paragraph.")
                        .build())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

来源示例 15（ruby）：

沿用程序文字说明4。

沿用程序文字说明5。

## [中文] 示例 15：为一个会话覆盖设置。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
## Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent_id: "agent_123",
  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."
        }
      ]
    }
  ]
)
puts result

覆盖只影响此会话，不修改已保存智能体或其他会话。提供的对象与数组替换整个字段，不与保存值合并；例如提供 tools 会替换整个工具列表。

请求字段见创建会话参考。

更新已有会话的设置

向 POST /v1/agents/sessions/{session_id} 发送含 agent 的请求，可为单个会话更改 model、reasoning.effort 或 service_tier。Beta 与正式版 API 协议都提供这些设置；同一次请求也可更新 metadata。

修改只影响更新完成后新消息启动的新轮次。已经在途的消息可能使用此前设置；活动轮次即使收到中途引导消息，也继续使用本轮设置。会话保留对话历史。所选模型必须支持最终组合，否则更新失败。

• agent 与 reasoning 会把提供的字段合并到当前设置；省略字段，包括推理摘要，保持不变。仅改模型会保留会话推理强度与服务层级。
• reasoning.effort: null 恢复所选模型默认强度。
• service_tier: null 恢复自动选择服务层级。
• 模型必须始终存在，不能提供 model: null；agent 和 reasoning 对象本身也不能为 null。
• metadata 替换整个映射。省略则保留，提供 null 或 {} 则清空。

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

来源示例 16（json）：

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

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

此端点不能更新 reasoning.summary、text、tools、instructions 或 multi_agent。需要改变这些设置时，创建新会话。

自动操作审查

把会话级 review 字段设为 "auto_review"，可自动审查受支持的批准请求。该字段与 agent 或 agent_id 同级，不放在智能体配置内部；创建会话时省略该字段，默认值为 "none"。

自动审查也会改变执行权限。启用前须核对执行环境前置条件。

只有在主任务空闲且输入提交处理已完成时，才能更新 review；之后的执行与恢复使用新设置。未满足这些条件时请求返回 409 Conflict，不应用任何更改。项目须已启用自动审查，会话也须支持该功能。配置及批准处理详见自动审查。

环境设置

创建会话时，将 environment 与 agent 并列提供，决定智能体在哪里运行命令和处理文件。

可选 none、openai_hosted 或 self_hosted。选择时机与环境管理职责见架构。

OpenAI 托管环境需选择容器规格，并配置软件包、初始文件与网络权限。环境模板可跨会话复用。自托管环境则由你准备计算资源并连接执行器。

环境字段见创建会话参考；技能、插件与模板见插件；执行结束后需保留的文件见文件与产物。