智慧體的設定決定其行為。你可以在建立工作階段時提供設定,也可以儲存設定以供日後使用。工作階段保留對話與工作內容,已儲存的智慧體則保留可重複使用的設定。
先指定模型與指示,再依任務需求加入工具與控制選項:
- 模型: 指定由哪個模型執行任務。
- 指示: 說明智慧體應執行哪些任務,以及應如何行動。
- 工具: 指定智慧體可執行的動作,例如搜尋網頁或呼叫你的函式。
- 推理與輸出: 設定模型的推理強度,以及回應的格式與詳細程度。
建立工作階段時,請在 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 連線或多智慧體任務委派。
指示與工具設定的總大小須小於 4 MiB(4,194,304 位元組),並為 Agents API 的中繼資料預留少許空間。如果設定過大導致工作階段無法啟動,請縮減指示與工具設定,再建立新的工作階段。
上傳至環境的檔案另有檔案限制。
儲存智慧體後,即可在多個工作階段中重複使用其設定。只需建立一次智慧體,之後每次啟動工作階段時,將其 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 會取代已儲存的工具清單。
如需查閱請求欄位,請參閱建立工作階段的 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 自動選擇服務層級:
123456{
"agent": {
"reasoning": { "effort": "low" },
"service_tier": null
}
}
更新工作階段不會影響已儲存的智慧體或其他工作階段。之後更新已儲存的智慧體,也不會影響此工作階段。
無法透過此端點更新 reasoning.summary、text、instructions 或 multi_agent。若要變更這些設定,請建立新的工作階段。如需查閱請求欄位,請參閱更新工作階段的 API 參考文件。
將工作階段層級的 review 欄位設為 "auto_review",即可自動審查支援此功能的核准請求。請將此欄位設在與 agent 或 agent_id 相同的層級,不要放在智慧體設定內。建立工作階段時若省略 review,預設值為 "none"。
自動審查也會變更執行權限。啟用前,請先確認環境符合先決條件。
等到主要任務處於閒置狀態,且所有輸入都已提交完畢,即可更新 review。後續執行與復原作業都會使用新設定。若在任一條件尚未滿足時要求變更模式,API 會傳回 409 Conflict,不會套用任何變更。請使用已啟用自動審查的專案,以及支援自動審查的工作階段。如需瞭解如何設定自動審查及處理核准請求,請參閱自動審查。
建立工作階段時,請將 environment 設在與 agent 相同的層級。環境設定決定智慧體在哪裡執行指令與處理檔案。
可選擇 none、openai_hosted 或 self_hosted。架構說明各選項的適用情境,以及各環境由誰管理。
若使用由 OpenAI 託管的環境,請選擇容器大小,並設定任務所需的套件、初始檔案與網路存取權。你可以在多個工作階段中重複使用同一個環境範本。若使用自行託管的環境,請備妥運算資源並連接執行器。
如需查閱環境欄位,請參閱建立工作階段的 API 參考文件。如需瞭解技能、外掛程式與範本,請參閱外掛程式。若要在執行結束後保留檔案,請參閱工作階段產出檔案。