智慧體組態定義了智慧體的行為。你可以在建立工作階段時提供組態，也可以儲存組態以供重複使用。工作階段保有對話與工作內容，儲存的智慧體則保有可重複使用的設定。
先設定模型與指示，再加入任務所需的工具與控制項：
- 模型： 由哪個模型執行工作。
- 指示： 智慧體應該做什麼，以及應如何行動。
- 工具： 智慧體可執行的動作，例如搜尋網頁或呼叫你的函式。
- 推理與輸出： 模型使用的推理程度，以及回應的格式與詳細程度。
建立工作階段時，透過 agent 傳入這些設定。以下範例提供了模型、指示和第一則使用者訊息：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18from 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import (
"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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "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 連線；如需委派工作的方法，請參閱多智慧體。
儲存智慧體，即可在不同工作階段重複使用其組態。只需建立一次，之後每次啟動工作階段時，將其 ID 作為 agent_id 傳入：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28import (
"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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14require "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。
- 提供的物件會取代整個欄位。若提供的
reasoning 只包含 effort，也會清除已儲存的 summary。
null 會重設接受此值的欄位。例如，reasoning: null 會還原模型的預設推理程度。
請在同一個請求中變更或重設新模型不支援的所有設定。
建立工作階段時，同時提供 agent_id 和 agent 即可自訂已儲存智慧體的組態。對於省略的設定（包括模型），工作階段會在建立時從已儲存的智慧體複製這些設定。
執行此範例前，請將範例值 agent_123 替換為已儲存智慧體的 ID：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31// 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// 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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# 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 會取代已儲存的工具清單。
如需請求欄位的詳細資訊，請參閱建立工作階段參考文件。
傳送包含 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 自動選擇服務層級：
123456{
"agent": {
"reasoning": { "effort": "low" },
"service_tier": null
}
}
更新工作階段不會變更已儲存的智慧體或其他工作階段。之後對已儲存智慧體的更新也不會變更此工作階段。
你無法透過此端點更新 reasoning.summary、text、tools、instructions 或 multi_agent。若要變更這些設定，請建立新的工作階段。
建立工作階段時，除了設定 agent，也請設定 environment。環境設定決定智慧體在哪裡執行指令與處理檔案。
選擇 none、openai_hosted 或 self_hosted。架構說明了各選項的適用情境，以及由誰管理環境。
若使用 OpenAI 託管環境，請設定任務所需的套件、初始檔案與網路存取權。你可以在不同工作階段重複使用環境範本。若使用自行託管環境，請準備運算資源並連接執行器。
如需環境欄位的詳細資訊，請參閱建立工作階段參考文件；如需技能、外掛程式與範本的資訊，請參閱外掛程式。若想在執行後保留檔案，請參閱工作階段產物。
