一律優先使用 Responses API 。這是 OpenAI 的旗艦 API,也是使用最新模型行為、內建工具、有狀態工作流程和智慧體功能的最佳途徑。
針對你的工作負載評估 GPT-6 系列模型 。需要最強能力時,使用 gpt-6-astra 。若要以低於 Astra 的成本處理複雜的程式設計和專業工作,使用 gpt-6.1-sol 。若要高效率地處理可重複執行的工作,使用 gpt-6-luna 。依模型在代表性任務上的表現選擇模型,避免將所有請求都送到能力最強的模型。
遷移至 GPT-6 時,請在支援的範圍內,保留目前模型在工作負載中負責的任務及實際使用的推理強度。需要搭配工具進行推理時,請使用 Responses API。GPT-6 Astra 和 GPT-6.1 Sol 必須透過 Responses 呼叫工具。GPT-6 Sol 和 GPT-6 Luna 只有在設定 reasoning_effort: "none" 時,才支援在 Chat Completions 中使用函式呼叫。推理強度不是 none 時,請移除 temperature、top_p 和 top_logprobs,並從 Chat Completions 請求中移除 logprobs。另外,請將 message.output_text.logprobs 從 Responses 的 include 陣列中移除。選擇模型或處理層級前,請確認是否符合資料駐留資格 。其他相容性檢查請參閱模型遷移指南 。變更提示詞或新增功能前,請先執行具代表性的評估。比較任務成功率、延遲、輸入、輸出、推理及快取寫入的 Token 數,以及每次成功完成任務的成本。
使用 reasoning.effort 決定模型回答前要投入多少推理。
GPT-6 Astra、GPT-6.1 Sol、GPT-6 Sol 和 GPT-6 Luna 支援 low、medium、high、xhigh 和 max。GPT-6 Sol 和 GPT-6 Luna 也支援 none,GPT-6 Astra 和 GPT-6.1 Sol 則不支援。推理強度越低,速度越快,使用的推理 Token 也越少。提高推理強度可讓模型有更多時間規劃、除錯、整合資訊,以及在多個步驟中權衡不同選擇。
如果工作主要是擷取資訊、路由、分類或例行改寫,請使用 low。如果模型需要診斷問題、比較選項、擬定計畫或分析程式碼邏輯,請使用 medium 或 high。只有在代表性評估顯示品質提升值得付出額外延遲與成本時,才使用 xhigh 或 max。若原先使用 minimal,或原先使用 none 而要遷移至 GPT-6 Astra 或 GPT-6.1 Sol,請先使用 low 並比較結果。其他情況下,請維持目前實際使用的強度,並依品質、延遲和成本目標測試調整後的效果。
對於難度最高且以品質為優先的工作負載,也請在相同推理強度下比較 reasoning.mode: "pro" 與標準模式。推理模式和推理強度可獨立設定。Pro 模式會讓模型投入更多運算後再傳回單一最終答案,這有助於提高可靠性,但也會增加延遲和 Token 用量。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 import OpenAI from "openai";
const openai = new OpenAI();
const prompt = [
"Our CI job started failing after a dependency bump.",
"",
"Error:",
"TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'",
"",
"Identify the likeliest root cause and the smallest safe fix.",
].join("\n");
const response = await openai.responses.create({
model: "gpt-6-astra",
reasoning: { effort: "xhigh", mode: "pro" },
input: prompt,
});
console.log(response.output_text); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 from openai import OpenAI
client = OpenAI()
prompt = """
Our CI job started failing after a dependency bump.
Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'
Identify the likeliest root cause and the smallest safe fix.
"""
response = client.responses.create(
model = "gpt-6-astra" ,
reasoning = { "effort" : "xhigh" , "mode" : "pro" },
input = prompt,
)
print (response.output_text) 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
32
33
34 package main
import (
"context"
"fmt"
"strings"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
prompt := strings.Join([]string{
"Our CI job started failing after a dependency bump.",
"",
"Error:",
"TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'",
"",
"Identify the likeliest root cause and the smallest safe fix.",
}, "\n")
reasoning := shared.ReasoningParam{Effort: shared.ReasoningEffortXhigh}
reasoning.SetExtraFields(map[string]any{"mode": "pro"})
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Reasoning: reasoning,
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(prompt)},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Our CI job started failing after a dependency bump. Error: TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'. Identify the likeliest root cause and the smallest safe fix.")
.reasoning(
Reasoning.builder()
.effort(ReasoningEffort.XHIGH)
.putAdditionalProperty("mode", JsonValue.from("pro"))
.build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 require "openai"
client = OpenAI::Client.new
prompt = <<~PROMPT
Our CI job started failing after a dependency bump.
Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'
Identify the likeliest root cause and the smallest safe fix.
PROMPT
response = client.responses.create(
model: "gpt-6-astra",
reasoning: {
effort: :xhigh,
mode: :pro
},
input: prompt
)
puts(response.output_text)
使用 GPT-6 模型的標準單一智慧體模式時,可在下一則使用者訊息之前加入 configuration_update 輸入項目,在兩次回應之間調整推理強度。請維持請求層級的 reasoning.effort 設定,讓原始提示詞前綴仍可使用快取。更新從下一次回應起生效,直到後續更新將其覆寫。設定更新無法與自動壓縮或截斷搭配使用,/responses/compact 也會拒絕包含設定更新的歷程記錄。若要壓縮歷程記錄,請加入 compaction_trigger 項目,並在壓縮後再加入一筆新的設定更新。
設定 text.verbosity
text.verbosity 是調整回答簡潔度與完整度的主要設定。產品需要快速、精簡的答案時,請調低詳細程度。需要更充分的說明、更清楚的結構或完整的背景資訊時,則請調高。降低詳細程度會減少輸出 Token,模型要生成的內容較少,因此能更快傳回結果。
在程式設計任務中,medium 和 high 通常會產生較長、較有條理且結構清楚的輸出。low 則會讓答案更精簡。
遷移時,請確認「請簡明扼要」之類的概括指示是否仍有幫助。建議使用 text.verbosity 控制預設的詳細程度,再透過提示詞指定必要內容、結構與長度。
提示詞也會影響品質、Token 用量、成本和延遲。調整詳細程度時,請一併參閱最新模型的提示詞最佳做法 ,包括其中針對程式設計智慧體的測試與驗證指引。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import OpenAI from "openai";
const openai = new OpenAI();
const incident = [
"Summarize this incident for the next on-call engineer.",
"- checkout latency spiked from 220 ms to 4.8 s",
"- only us-east-1 was affected",
"- rollback is complete",
"- likely trigger: cache stampede after deploy",
].join("\n");
const response = await openai.responses.create({
model: "gpt-6-astra",
text: { verbosity: "low" },
input: incident,
});
console.log(response.output_text); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model = "gpt-6-astra" ,
text = { "verbosity" : "low" },
input = """
Summarize this incident for the next on-call engineer.
- checkout latency spiked from 220 ms to 4.8 s
- only us-east-1 was affected
- rollback is complete
- likely trigger: cache stampede after deploy
""" ,
)
print (response.output_text) 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 package main
import (
"context"
"fmt"
"strings"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
incident := strings.Join([]string{
"Summarize this incident for the next on-call engineer.",
"- checkout latency spiked from 220 ms to 4.8 s",
"- only us-east-1 was affected",
"- rollback is complete",
"- likely trigger: cache stampede after deploy",
}, "\n")
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Text: responses.ResponseTextConfigParam{Verbosity: "low"},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(incident)},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseTextConfig;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Summarize this incident for the next on-call engineer: checkout latency spiked from 220 ms to 4.8 s, only us-east-1 was affected, rollback is complete, and the likely trigger was a cache stampede.")
.text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 require "openai"
client = OpenAI::Client.new
incident = <<~INCIDENT
Summarize this incident for the next on-call engineer.
- checkout latency spiked from 220 ms to 4.8 s
- only us-east-1 was affected
- rollback is complete
- likely trigger: cache stampede after deploy
INCIDENT
response = client.responses.create(
model: "gpt-6-astra",
text: { verbosity: :low },
input: incident
)
puts(response.output_text)
phase 是對話歷程中助理訊息的標籤,讓模型知道先前的助理訊息是工作過程中的說明,還是最終答案。對於進度更新、呼叫工具前的說明及其他過程中的訊息,請使用 phase: "commentary"。對於已完成的回應,請使用 phase: "final_answer"。
舉例來說,助理可能會傳送以下訊息:
1
2
3
4
5 {
"role" : "assistant" ,
"phase" : "commentary" ,
"content" : "I'm checking the logs and comparing them to the last successful deploy."
}
這則訊息只是在說明進度,助理尚未給出答案。稍後,助理可能會傳送以下訊息:
1
2
3
4
5 {
"role" : "assistant" ,
"phase" : "final_answer" ,
"content" : "The deploy failed because the migration referenced a column that does not exist in production."
}
在執行時間長或頻繁使用工具的工作流程中,助理可能在完成前先向使用者顯示進度,此時這個標籤特別有用。在後續請求中將對話歷程傳回給 gpt-5.3-codex 或更新的模型時,請保留並重新傳送助理訊息上的 phase ,讓模型能區分進度更新與最終結果。這有助於減少過早停止的情況,讓智慧體更有可能持續工作,直到得出最終答案。
不必在每個請求中載入完整的工具目錄。請使用工具搜尋 ,加入 {"type": "tool_search"},並以 defer_loading: true 標記載入成本較高的工具定義。這樣模型就能在執行時只載入所需的工具。請求開始時,模型只會看到搜尋工具的名稱和說明。如果模型判斷需要某個延後載入的工具,就會執行工具搜尋,此時才會將相應的工具定義載入上下文。載入後,模型才會呼叫這些工具。這樣可以節省 Token 並維持快取效能。
工具搜尋有兩種模式:
託管式工具搜尋 較為簡單。如果你已經知道哪些工具可能供這次請求使用,請選用此模式。
由用戶端執行工具搜尋 適用於必須由應用程式決定哪些工具可用的情況,例如依使用者所屬的租戶、專案、權限或內部登錄資料決定。
除非應用程式確實需要自行控制工具探索流程,否則請先使用託管式工具搜尋 。
依使用者意圖將工具分組,並盡可能使用命名空間或 MCP 伺服器。比起從一長串未分組的函式中挑選,模型更容易從少數幾個界線清楚的群組中做選擇。為了讓 Token 使用效率和模型效能達到最佳表現,建議每個命名空間的函式數量控制在約 10 個以下。
命名空間的說明應簡短,且能清楚區別各個群組。將詳細指示放在延後載入的工具定義中,避免把所有工具放進同一個龐大的命名空間。
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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61 import OpenAI from "openai";
const openai = new OpenAI();
const billingNamespace: OpenAI.Responses.NamespaceTool = {
type: "namespace",
name: "billing",
description: "Billing tools for invoices, payments, taxes, and credits.",
tools: [
{
type: "function",
name: "lookup_invoice",
description:
"Look up invoice state, taxes, credits, and payment attempts.",
parameters: {
type: "object",
properties: {
invoice_id: { type: "string" },
},
required: ["invoice_id"],
additionalProperties: false,
},
strict: true,
defer_loading: true,
},
],
};
const crmNamespace: OpenAI.Responses.NamespaceTool = {
type: "namespace",
name: "crm",
description:
"CRM tools for account ownership, plans, health, and payment history.",
tools: [
{
type: "function",
name: "get_account",
description: "Fetch account owner, plan, health, and payment history.",
parameters: {
type: "object",
properties: {
account_id: { type: "string" },
},
required: ["account_id"],
additionalProperties: false,
},
strict: true,
defer_loading: true,
},
],
};
const response = await openai.responses.create({
model: "gpt-6-astra",
input:
"Find the right billing tool and explain why invoice INV-1043 still " +
"shows overdue after a payment yesterday.",
tools: [billingNamespace, crmNamespace, { type: "tool_search" }],
});
console.log(response.output); 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60 from openai import OpenAI
client = OpenAI()
billing_namespace = {
"type" : "namespace" ,
"name" : "billing" ,
"description" : "Billing tools for invoices, payments, taxes, and credits." ,
"tools" : [
{
"type" : "function" ,
"name" : "lookup_invoice" ,
"description" : "Look up invoice state, taxes, credits, and payment attempts." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"invoice_id" : { "type" : "string" },
},
"required" : [ "invoice_id" ],
"additionalProperties" : False ,
},
"strict" : True ,
"defer_loading" : True ,
}
],
}
crm_namespace = {
"type" : "namespace" ,
"name" : "crm" ,
"description" : "CRM tools for account ownership, plans, health, and payment history." ,
"tools" : [
{
"type" : "function" ,
"name" : "get_account" ,
"description" : "Fetch account owner, plan, health, and payment history." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"account_id" : { "type" : "string" },
},
"required" : [ "account_id" ],
"additionalProperties" : False ,
},
"strict" : True ,
"defer_loading" : True ,
}
],
}
response = client.responses.create(
model = "gpt-6-astra" ,
input = (
"Find the right billing tool and explain why invoice INV-1043 still "
"shows overdue after a payment yesterday."
),
tools = [billing_namespace, crm_namespace, { "type" : "tool_search" }],
)
print (response.output) 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
billing := namespaceTool(
"billing",
"Billing tools for invoices, payments, taxes, and credits.",
"lookup_invoice",
"Look up invoice state, taxes, credits, and payment attempts.",
"invoice_id",
)
crm := namespaceTool(
"crm",
"CRM tools for account ownership, plans, health, and payment history.",
"get_account",
"Fetch account owner, plan, health, and payment history.",
"account_id",
)
toolSearch := responses.ToolUnionParam{OfToolSearch: &responses.ToolSearchToolParam{}}
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(
"Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.",
)},
Tools: []responses.ToolUnionParam{billing, crm, toolSearch},
})
if err != nil {
panic(err)
}
fmt.Println(response.Output)
}
func namespaceTool(namespace, namespaceDescription, name, description, argument string) responses.ToolUnionParam {
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
argument: map[string]any{"type": "string"},
},
"required": []string{argument},
"additionalProperties": false,
}
function := responses.NamespaceToolToolFunctionParam{
Name: name, Description: openai.String(description), Parameters: parameters, Strict: openai.Bool(true), DeferLoading: openai.Bool(true),
}
return responses.ToolParamOfNamespace(
namespaceDescription,
namespace,
[]responses.NamespaceToolToolUnionParam{{OfFunction: &function}},
)
} 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.NamespaceTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ToolSearchTool;
import java.util.List;
import java.util.Map;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.")
.addTool(
namespace(
"billing",
"Billing tools for invoices, payments, taxes, and credits.",
"lookup_invoice",
"Look up invoice state, taxes, credits, and payment attempts.",
"invoice_id"))
.addTool(
namespace(
"crm",
"CRM tools for account ownership, plans, health, and payment history.",
"get_account",
"Fetch account owner, plan, health, and payment history.",
"account_id"))
.addTool(ToolSearchTool.builder().execution(ToolSearchTool.Execution.SERVER).build())
.build();
client.responses().create(params).output().forEach(System.out::println);
private static NamespaceTool namespace(
String name,
String description,
String function,
String functionDescription,
String argument) {
return NamespaceTool.builder()
.name(name)
.description(description)
.addTool(
NamespaceTool.Tool.Function.builder()
.name(function)
.description(functionDescription)
.deferLoading(true)
.strict(true)
.parameters(
JsonValue.from(
Map.of(
"type",
"object",
"properties",
Map.of(argument, Map.of("type", "string")),
"required",
List.of(argument),
"additionalProperties",
false)))
.build())
.build();
} 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48 require "openai"
def namespace_tool(name, description, function_name, function_description, argument)
{
type: :namespace,
name: name,
description: description,
tools: [
{
type: :function,
name: function_name,
description: function_description,
defer_loading: true,
strict: true,
parameters: {
type: "object",
properties: { argument => { type: "string" } },
required: [argument],
additionalProperties: false
}
}
]
}
end
client = OpenAI::Client.new
billing = namespace_tool(
"billing",
"Billing tools for invoices, payments, taxes, and credits.",
"lookup_invoice",
"Look up invoice state, taxes, credits, and payment attempts.",
"invoice_id"
)
crm = namespace_tool(
"crm",
"CRM tools for account ownership, plans, health, and payment history.",
"get_account",
"Fetch account owner, plan, health, and payment history.",
"account_id"
)
response = client.responses.create(
model: "gpt-6-astra",
input: "Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.",
tools: [billing, crm, { type: :tool_search }]
)
puts(response.output)
以程式呼叫工具 可讓支援此功能的模型撰寫 JavaScript,在託管的執行環境中呼叫符合條件的工具,並精簡中間結果。這項功能適合範圍明確的工作階段,例如先用程式碼篩選、聯結、排序、去除重複項目、合併或檢查大量工具結果,再將較精簡的結構化結果傳回模型。
加入 programmatic_tool_calling 工具,並為每個符合條件的工具個別啟用此功能。只允許程式呼叫的工具請設定 allowed_callers: ["programmatic"]。若模型也可以直接呼叫該工具,請設定 allowed_callers: ["direct", "programmatic"]。如果每次呼叫的結果都可能改變模型的下一個決定、動作需要核准,或最終答案必須保留引用來源或工具原生產出物,請維持直接呼叫。記錄工具傳回的欄位及發生錯誤時的行為,讓模型無須先檢視結果就能撰寫正確的程式。
工具呼叫迴圈必須能處理 program 和 program_output 項目,以及程式發出的 function_call 項目和相應的 function_call_output 項目。保留每個 call_id,並將函式呼叫的 caller 複製到對應的輸出中,讓服務能繼續執行正確的程式。
請同時測試 program_output 和助理的最終訊息。即使程式結果正確,最終答案仍可能不完整。以同一個工作流程直接呼叫工具,並比較兩種方式的任務成功率、必要佐證、Token 總數、延遲及成本。
多智慧體功能 可讓 GPT-6 等支援此功能的模型,將彼此獨立的工作交給子代理程式,再整合各自的結果。如果能將研究、分析或實作拆成具體且範圍明確的任務,讓各任務使用獨立的上下文並平行執行,就適合使用此功能。
在請求中將 multi_agent.enabled 設為 true。使用 HTTP 時,請透過 Beta 版 Responses SDK 的 client.beta.responses 發出請求,並將 responses_multi_agent=v1 傳入 betas。直接使用 HTTP 或透過 WebSocket 連線時,請傳送 OpenAI-Beta: responses_multi_agent=v1。多智慧體功能仍在 Beta 階段,項目的結構描述可能變動。
如果任務簡短、每個步驟都依賴前一步的結果,或多項工作會寫入同一個可變資源,建議使用單一智慧體。子代理程式可能增加 Token 用量,因此請先使用 max_concurrent_subagents 的預設值 3,再衡量端對端品質、延遲與成本。對於頻繁使用工具或執行時間長的多智慧體工作流程,WebSocket 模式可以降低接續執行的額外負擔。
啟用多智慧體功能前,請考量目前的限制:不支援 /responses/compact、reasoning.summary 和 max_tool_calls。伺服器會自動壓縮根智慧體及每個子代理程式的上下文。
使用 GPT-6 模型時,如果應用程式執行工具期間模型可以繼續工作,請在函式或自訂工具上設定 async: true。提早啟動耗時的工具呼叫,讓模型先處理其他獨立工作。應用程式仍負責執行及追蹤呼叫,然後在後續的 Responses 請求中使用原始 call_id 傳回結果。非同步執行不適用於內建工具或以程式發出的工具呼叫。在多智慧體模式下,請勿將非同步工具與平行工具呼叫搭配使用。完整流程請參閱非同步工具呼叫 。
內建工具 是 API 原生提供的功能。你可以直接讓模型使用 Responses API 已提供的工具,省去逐一自行開發的工作。模型會自行決定何時使用這些工具。
OpenAI 持續新增原生工具。如果內建工具符合你的工作流程,請優先使用。如果現有原生工具無法滿足任務需求,再建立自訂工具。目前的內建工具和相關選項包括:
網頁搜尋 :在網路上搜尋最新資訊
檔案搜尋 :搜尋已上傳的檔案或向量儲存區
程式碼解譯器 :執行 Python 以分析資料、進行數學運算、繪製圖表及處理檔案
Shell :在託管容器或自己的執行環境中執行 Shell 指令
電腦 :透過螢幕截圖、點選、輸入文字和捲動來操作使用者介面
圖像生成 :生成或編輯影像
MCP/連接器 :將模型連接至外部服務與工具
技能 :附加可重複使用的指示套件及工作流程檔案
套用修補程式 :以結構化方式修改程式碼
模型的表現也是優先使用內建工具的原因。內建工具符合模型後訓練的資料分布,也就是說,模型的訓練和評估都涵蓋這些工具的結構、行為及輸出。相較於新工具,使用內建工具時,OpenAI 模型更能選對工具,執行更順暢,失敗的情況也更少。
壓縮 是一種上下文工程工具,用來決定模型在多個回合之間保留哪些資訊。對於長時間執行的智慧體,除了要考慮「會不會達到上下文上限?」,還要留意舊訊息、工具記錄、重試記錄和過時的細節可能排擠模型需要的狀態資訊。
透過壓縮,你可以控制上下文大小,同時保留後續回合所需的狀態。完成重要階段後,例如結束某個除錯階段或縮小根本原因的範圍時,可以壓縮先前的上下文視窗,再從壓縮後的輸出繼續工作。這樣一來,下一回合就能聚焦於重要狀態,無須帶入所有中間推理、失敗的指令和已不適用的推理分支,有助於維持模型的表現。
你可以透過兩種方式使用壓縮:
交由伺服器處理 :如果使用 previous_response_id,請啟用 context_management 並設定 compact_threshold。對話過大時,伺服器會自動壓縮對話。你只需繼續傳送最新的使用者訊息。
自行處理 :如果自行管理完整的輸入陣列,請呼叫 client.responses.compact()。它會傳回較小的上下文視窗。請在下一次呼叫 responses.create() 時直接使用傳回的輸出。
請勿編輯壓縮後的輸出。 這份輸出是讓模型繼續工作的機器狀態,並非供人閱讀的摘要。請原樣傳遞,再加入下一則使用者訊息。
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 import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";
const openai = new OpenAI();
// Full window collected from a long debugging session:
// user messages, assistant outputs, tool calls, and tool outputs.
const longWindow = sessionItems;
const compacted = await openai.responses.compact({
model: "gpt-6-astra",
input: longWindow,
});
const nextResponse = await openai.responses.create({
model: "gpt-6-astra",
store: false,
input: [
// Preserve replayable compacted items.
...toResponseInputItems(compacted.output),
{
type: "message",
role: "user",
content:
"We found the bad cache invalidation path. Write the fix plan " +
"and the verification checklist.",
},
],
});
console.log(nextResponse.output_text); 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 from openai import OpenAI
client = OpenAI()
# Full window collected from a long debugging session:
# user messages, assistant outputs, tool calls, and tool outputs.
long_window = session_items
compacted = client.responses.compact(
model = "gpt-6-astra" ,
input = long_window,
)
next_response = client.responses.create(
model = "gpt-6-astra" ,
store = False ,
input = [
* compacted.output, # Use compact output as-is.
{
"type" : "message" ,
"role" : "user" ,
"content" : (
"We found the bad cache invalidation path. Write the fix plan "
"and the verification checklist."
),
},
],
)
print (next_response.output_text) 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
longWindow := []responses.ResponseInputItemUnionParam{
responses.ResponseInputItemParamOfMessage("Find the cache invalidation bug in this debugging session.", responses.EasyInputMessageRoleUser),
}
compacted, err := client.Responses.Compact(context.Background(), responses.ResponseCompactParams{
Model: "gpt-6-astra",
Input: responses.ResponseCompactParamsInputUnion{OfResponseInputItemArray: longWindow},
})
if err != nil {
panic(err)
}
input := append(outputAsInput(compacted.Output),
responses.ResponseInputItemParamOfMessage(
"We found the bad cache invalidation path. Write the fix plan and the verification checklist.",
responses.EasyInputMessageRoleUser,
),
)
nextResponse, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Store: openai.Bool(false),
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
})
if err != nil {
panic(err)
}
fmt.Println(nextResponse.OutputText())
}
func outputAsInput(output []responses.ResponseOutputItemUnion) []responses.ResponseInputItemUnionParam {
input := make([]responses.ResponseInputItemUnionParam, 0, len(output))
for _, item := range output {
var converted responses.ResponseInputItemUnion
if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
panic(err)
}
input = append(input, converted.ToParam())
}
return input
} 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseCompactParams;
import com.openai.models.responses.ResponseCompactionItemParam;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.ArrayList;
var compacted =
client
.responses()
.compact(
ResponseCompactParams.builder()
.model("gpt-6-astra")
.input("Find the cache invalidation bug in this debugging session.")
.build());
var input = new ArrayList<ResponseInputItem>();
for (var item : compacted.output()) {
item.message().map(ResponseInputItem::ofResponseOutputMessage).ifPresent(input::add);
item.reasoning().map(ResponseInputItem::ofReasoning).ifPresent(input::add);
item.compaction()
.map(
value ->
ResponseInputItem.ofCompaction(
ResponseCompactionItemParam.builder()
.id(value.id())
.encryptedContent(value.encryptedContent())
.build()))
.ifPresent(input::add);
}
input.add(
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content(
"We found the bad cache invalidation path. Write the fix plan and the verification checklist.")
.build()));
client
.responses()
.create(
ResponseCreateParams.builder()
.model("gpt-6-astra")
.inputOfResponse(input)
.store(false)
.build())
.output()
.stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 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 require "openai"
client = OpenAI::Client.new
long_window = [
{
role: :user,
content: "Find the cache invalidation bug in this debugging session."
}
]
compacted = client.responses.compact(
model: "gpt-6-astra",
input: long_window
)
input = compacted.output.dup
input << {
role: :user,
content: "We found the bad cache invalidation path. Write the fix plan and the verification checklist."
}
response = client.responses.create(
model: "gpt-6-astra",
store: false,
input: input
)
puts(response.output_text)
多個請求重複使用相同的長前綴時,提示詞快取 會自動降低延遲和成本。先放入固定的指示、範例和參考資料,再放入因使用者而異的動態內容。保持工具定義與順序一致,將新的對話回合附加在末尾,避免改寫先前的上下文。
GPT-5.6 開始支援明確設定提示詞快取。預設仍使用隱含快取,但 GPT-5.6 和後續系列模型也支援明確指定快取斷點,以及設定適用於整個請求的快取原則。如果固定前綴後面接著會變動的後綴,請在可重複使用的內容結束處明確加入 prompt_cache_breakpoint。只有在請求應僅使用你提供的斷點、完全不使用隱含斷點時,才將 prompt_cache_options.mode 設為 explicit。較早的模型仍只支援自動提示詞快取。
從 GPT-5.5 或更早版本遷移時,請將 prompt_cache_retention 替換為 prompt_cache_options.ttl: "30m"。變更快取設定前,請先參閱各模型的提示詞快取差異 。
在 GPT-5.6 和後續系列模型上,快取寫入費率是未快取輸入 Token 費率的 1.25 倍。請記錄 cached_tokens 和 cache_write_tokens,再比較寫入量和後續的快取讀取量,以衡量淨成本並調整斷點位置。
對於共用可重複使用前綴的請求,請使用固定的 prompt_cache_key。這有助於將相關請求路由至同一個快取,並讓 GPT-5.6 之前的模型達到最佳快取命中率。對於流量較大的群組,請依照使用更多快取鍵分散流量的指引 操作。
在 GPT-5.6 和更新的模型上,prompt_cache_key 是選用設定,即使不設定也能達到最佳快取命中率。你可以使用它為不同客戶、使用者或工作區分別統計快取用量,方便向各群組說明快取 Token 用量及計費方式。請為每位客戶指派不同的快取鍵,並在該客戶的相關請求中使用同一個鍵。使用不同的鍵也有助於防止跨客戶探測快取命中情形。請參閱使用快取鍵分別統計快取用量 。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 import OpenAI from "openai";
const openai = new OpenAI();
const instructions = [
"You are the support agent for Acme.",
"Follow the Acme support policy and escalation rubric.",
"Use the same tone, safety rules, and tool plan for each ticket.",
].join("\n");
const response = await openai.responses.create({
model: "gpt-6-astra",
prompt_cache_key: "tenant-acme-support-agent",
instructions,
input: "Summarize the current escalation for the on-call lead.",
});
console.log(response.output_text); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 from openai import OpenAI
client = OpenAI()
instructions = """
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
"""
response = client.responses.create(
model = "gpt-6-astra" ,
prompt_cache_key = "tenant-acme-support-agent" ,
instructions = instructions,
input = "Summarize the current escalation for the on-call lead." ,
)
print (response.output_text) 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 package main
import (
"context"
"fmt"
"strings"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
instructions := strings.Join([]string{
"You are the support agent for Acme.",
"Follow the Acme support policy and escalation rubric.",
"Use the same tone, safety rules, and tool plan for each ticket.",
}, "\n")
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
PromptCacheKey: openai.String("tenant-acme-support-agent"),
Instructions: openai.String(instructions),
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Summarize the current escalation for the on-call lead.")},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.instructions(
"You are the support agent for Acme.\n"
+ "Follow the Acme support policy and escalation rubric.\n"
+ "Use the same tone, safety rules, and tool plan for each ticket.")
.input("Summarize the current escalation for the on-call lead.")
.promptCacheKey("tenant-acme-support-agent")
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new()
{
Model = "gpt-6-astra",
PromptCacheKey = "tenant-acme-support-agent",
Instructions = "Follow the Acme support policy and escalation rubric.",
};
options.InputItems.Add(
ResponseItem.CreateUserMessageItem("Summarize the current escalation for the on-call lead.")
);
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText()); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 require "openai"
client = OpenAI::Client.new
instructions = <<~INSTRUCTIONS
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
INSTRUCTIONS
response = client.responses.create(
model: "gpt-6-astra",
prompt_cache_key: "tenant-acme-support-agent",
instructions: instructions,
input: "Summarize the current escalation for the on-call lead."
)
puts(response.output_text)
使用 reasoning.encrypted_content
GPT-6 等支援此功能的模型可以在多次呼叫之間保留推理內容 。任務目標、假設和優先順序維持不變時,請使用 reasoning.context: "all_turns"。如果先前的推理已不再相關,而且可能讓模型受限於過時的做法,請使用 current_turn。如果省略 reasoning.context 或將其設為 auto,請檢查回應中的 reasoning.context 欄位,確認實際生效的模式。
只有在先前的推理項目仍可取得時,才能沿用已保留的推理內容 。對於已儲存的回應,請使用 previous_response_id。如果你的零資料保留(ZDR) 要求不允許儲存回應資料,可以透過加密推理內容,以無狀態方式接續工作。
回應輸出中的推理項目預設包含加密推理內容。你可以從各推理項目的 encrypted_content 屬性取得這些內容。應用程式無須解讀該值,只需原樣保留每個傳回的推理項目,並在下一回合將其傳回模型,讓模型據此繼續執行工作流程。
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
32
33 import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";
const openai = new OpenAI();
const history: OpenAI.Responses.ResponseInput = [
{
role: "user",
content: "Investigate why invoice INV-1043 has mismatched tax totals.",
},
];
const first = await openai.responses.create({
model: "gpt-6-astra",
store: false,
reasoning: { effort: "medium", context: "current_turn" },
input: history,
});
history.push(...toResponseInputItems(first.output));
history.push({
role: "user",
content: "Now write the customer-facing explanation in plain English.",
});
const second = await openai.responses.create({
model: "gpt-6-astra",
store: false,
reasoning: { effort: "medium", context: "all_turns" },
input: history,
});
console.log(second.output_text); 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
32
33
34 from openai import OpenAI
client = OpenAI()
history = [
{
"role" : "user" ,
"content" : "Investigate why invoice INV-1043 has mismatched tax totals." ,
}
]
first = client.responses.create(
model = "gpt-6-astra" ,
store = False ,
reasoning = { "effort" : "medium" , "context" : "current_turn" },
input = history,
)
history.extend(item.to_dict() for item in first.output)
history.append(
{
"role" : "user" ,
"content" : "Now write the customer-facing explanation in plain English." ,
}
)
second = client.responses.create(
model = "gpt-6-astra" ,
store = False ,
reasoning = { "effort" : "medium" , "context" : "all_turns" },
input = history,
)
print (second.output_text) 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
history := []responses.ResponseInputItemUnionParam{
responses.ResponseInputItemParamOfMessage("Investigate why invoice INV-1043 has mismatched tax totals.", responses.EasyInputMessageRoleUser),
}
first, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Store: openai.Bool(false),
Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortMedium, Context: shared.ReasoningContextCurrentTurn},
Include: []responses.ResponseIncludable{responses.ResponseIncludableReasoningEncryptedContent},
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: history},
})
if err != nil {
panic(err)
}
history = append(history, outputAsInput(first.Output)...)
history = append(history, responses.ResponseInputItemParamOfMessage(
"Now write the customer-facing explanation in plain English.",
responses.EasyInputMessageRoleUser,
))
second, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Store: openai.Bool(false),
Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortMedium, Context: shared.ReasoningContextAllTurns},
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: history},
})
if err != nil {
panic(err)
}
fmt.Println(second.OutputText())
}
func outputAsInput(output []responses.ResponseOutputItemUnion) []responses.ResponseInputItemUnionParam {
input := make([]responses.ResponseInputItemUnionParam, 0, len(output))
for _, item := range output {
var converted responses.ResponseInputItemUnion
if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
panic(err)
}
input = append(input, converted.ToParam())
}
return input
} 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.Reasoning;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseIncludable;
import com.openai.models.responses.ResponseInputItem;
import java.util.ArrayList;
var history = new ArrayList<ResponseInputItem>();
history.add(
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("Investigate why invoice INV-1043 has mismatched tax totals.")
.build()));
var first =
client
.responses()
.create(
ResponseCreateParams.builder()
.model("gpt-6-astra")
.inputOfResponse(history)
.store(false)
.reasoning(
Reasoning.builder()
.effort(com.openai.models.ReasoningEffort.MEDIUM)
.putAdditionalProperty("context", JsonValue.from("current_turn"))
.build())
.addInclude(ResponseIncludable.of("reasoning.encrypted_content"))
.build());
first.output().stream()
.map(item -> JsonValue.from(item).convert(ResponseInputItem.class))
.forEach(history::add);
history.add(
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("Now write the customer-facing explanation in plain English.")
.build()));
client
.responses()
.create(
ResponseCreateParams.builder()
.model("gpt-6-astra")
.inputOfResponse(history)
.store(false)
.reasoning(
Reasoning.builder()
.effort(com.openai.models.ReasoningEffort.MEDIUM)
.putAdditionalProperty("context", JsonValue.from("all_turns"))
.build())
.build())
.output()
.stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 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
32
33
34
35
36
37 require "openai"
client = OpenAI::Client.new
history = [
{
role: :user,
content: "Investigate why invoice INV-1043 has mismatched tax totals."
}
]
first = client.responses.create(
model: "gpt-6-astra",
store: false,
reasoning: {
effort: :medium,
context: :current_turn
},
include: ["reasoning.encrypted_content"],
input: history
)
history.concat(first.output)
history << {
role: :user,
content: "Now write the customer-facing explanation in plain English."
}
second = client.responses.create(
model: "gpt-6-astra",
store: false,
reasoning: {
effort: :medium,
context: :all_turns
},
input: history
)
puts(second.output_text)
影像的 detail 預設為 auto,尺寸處理方式依模型而異。大型影像可能使用更多輸入 Token,並增加延遲。請查看各模型的影像尺寸處理方式一覽表 ,並在部署前用所選模型實測影像 Token 用量和限制。
請依任務選擇 detail 。你可以調整影像尺寸,在細微的視覺特徵不重要時使用 low,或使用 high 進行標準的高傳真影像理解。如果任務涉及大型影像、密集資訊、精確座標、OCR、位置辨識或視覺檢查,且更多細節能提高品質,請在模型支援時使用 original。部署前,請測量最差情況下的影像 Token 用量和延遲。
如果應用程式為個別終端使用者提供服務,請隨每個請求傳送固定且能保護隱私的 safety_identifier 。這有助於 OpenAI 偵測濫用行為,也讓團隊能透過一致的識別碼追查違反政策的情形,並降低單一使用者的濫用行為影響組織內其他人存取服務的可能性。
請將使用者名稱或電子郵件地址雜湊後再傳送,避免直接傳送可識別身分的資訊。對於未登入的使用者,請使用固定的工作階段 ID。
使用 GPT-6 Astra 建立智慧體工作流程時,請預先規劃如何處理行為偏離監控 事件。如果請求傳回 403 且錯誤碼為 misalignment_policy_violation,請停止為該對話派送動作,並且不要自動重試遭封鎖的工作流程。也請處理串流期間發生的錯誤,並檢查可能已執行的動作。如果團隊需要接收專案警示,請訂閱 safety.alert.created。即使使用 Webhook,仍須處理請求錯誤。請參閱指南,瞭解哪些 Responses 請求可能被自動停止。
決定如何復原之前,請先檢查 HTTP 狀態碼和 error.code。如果收到 429 且錯誤碼為 slow_down,表示請求速率上升過快。若有 Retry-After 標頭,請依其指示操作,降低流量後再逐步提高。如果收到 503 且錯誤碼為 server_is_overloaded,表示所請求的模型暫時過載。若有 Retry-After 標頭,請依其指示等待後再重試。如果沒有該標頭,請以指數方式延長重試間隔,加入隨機抖動,並限制重試次數。計費、支出或配額錯誤必須先處理才能重試,請勿將所有 429 錯誤都視為暫時的速率限制。請參閱速率限制 及錯誤碼 。
對於可能耗時較長的請求,請使用 background=True 。API 會啟動作業並傳回 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
28 // Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const openai = new OpenAI();
const logBundleFileId = "file_123";
let job = await openai.responses.create({
model: "gpt-6-astra",
background: true,
store: false,
input: "Analyze this large log bundle and cluster the primary failure modes.",
tools: [
{
type: "code_interpreter",
container: {
type: "auto",
file_ids: [logBundleFileId],
},
},
],
});
while (job.status === "queued" || job.status === "in_progress") {
await new Promise((resolve) => setTimeout(resolve, 2000));
job = await openai.responses.retrieve(job.id);
}
console.log(job.output_text); 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 # Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
import time
client = OpenAI()
log_bundle_file_id = "file_123"
job = client.responses.create(
model = "gpt-6-astra" ,
background = True ,
store = False ,
input = "Analyze this large log bundle and cluster the primary failure modes." ,
tools = [
{
"type" : "code_interpreter" ,
"container" : {
"type" : "auto" ,
"file_ids" : [log_bundle_file_id],
},
}
],
)
while job.status in { "queued" , "in_progress" }:
time.sleep( 2 )
job = client.responses.retrieve(job.id)
print (job.output_text) 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
32
33
34
35 package main
import (
"context"
"fmt"
"time"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolParamOfCodeInterpreter(responses.ToolCodeInterpreterContainerCodeInterpreterContainerAutoParam{
FileIDs: []string{"file_abc123"},
})
job, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Background: openai.Bool(true),
Store: openai.Bool(false),
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Analyze this large log bundle and cluster the primary failure modes.")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
for job.Status == responses.ResponseStatusQueued || job.Status == responses.ResponseStatusInProgress {
time.Sleep(2 * time.Second)
job, err = client.Responses.Get(context.Background(), job.ID, responses.ResponseGetParams{})
if err != nil {
panic(err)
}
}
fmt.Println(job.OutputText())
} 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
32
33
34
35
36 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseStatus;
import com.openai.models.responses.Tool;
String fileId = "file_abc123";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("Analyze this large log bundle and cluster the primary failure modes.")
.background(true)
.store(false)
.addCodeInterpreterTool(
Tool.CodeInterpreter.Container.CodeInterpreterToolAuto.builder()
.addFileId(fileId)
.build())
.build();
var response = client.responses().create(params);
while (response.status().filter(ResponseStatus.QUEUED::equals).isPresent()
|| response.status().filter(ResponseStatus.IN_PROGRESS::equals).isPresent()) {
Thread.sleep(1000);
response = client.responses().retrieve(response.id());
}
if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty()) {
throw new IllegalStateException(
"Research ended with status: " + response.status().orElseThrow());
}
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 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 require "openai"
client = OpenAI::Client.new
job = client.responses.create(
model: "gpt-6-astra",
background: true,
store: false,
input: "Analyze this large log bundle and cluster the primary failure modes.",
tools: [
{
type: :code_interpreter,
container: {
type: :auto,
file_ids: ["file_abc123"]
}
}
]
)
while [:queued, :in_progress].include?(job.status)
sleep(2)
job = client.responses.retrieve(job.id)
end
puts(job.output_text)
你可以搭配 stream=True 接收進度事件,但等到第一個事件的時間可能比一般請求更長。
在使用者介面中,背景模式可以這樣呈現:「作業執行中,你可以在這裡查看進度。完成後,結果會顯示在這裡。」
WebSocket 模式 專為長時間執行且頻繁呼叫工具的工作流程設計。保持連線開啟,每次只要傳送新的輸入項目和 previous_response_id,即可接續執行。對於包含至少 20 次工具呼叫的工作流程,我們觀察到端對端執行速度最多可提升約 40%。
運作方式 :第一則訊息和一般 Responses 請求類似,包含模型、指示、工具和使用者輸入。伺服器會以串流方式傳回事件。如果模型要求呼叫工具,應用程式就執行該工具。接著,透過同一個通訊端傳送另一個 response.create 事件,附上先前的 previous_response_id 和新的項目,無須另發 HTTP 請求。這正是延遲降低的原因。使用一般 HTTP 時,每次接續執行都需要新的請求。使用 WebSocket 模式時,連線保持開啟,而且該連線最近一次回應的狀態仍在記憶體中,可供直接使用。下一回合接續該回應時,服務所需的準備工作就較少。
如果工作流程只需發出一個請求、取得一個答案,請繼續使用 HTTP 。如果工作流程類似長時間執行的智慧體,請試用 WebSocket 模式。
若在同一條連線上平行進行多個對話,請為各對話使用不同的 stream_id 值,並依 stream_id 分派交錯抵達的事件。每條連線最多支援 16 個進行中的回應,同一串流上的請求則依序執行。每條連線最長可維持 60 分鐘。接續執行時,previous_response_id 的用法與 HTTP 模式相同,且各串流的最新回應會保留在該連線專用的快取中。
注意:WebSocket 模式可搭配 ZDR 使用,因為資料只會保存在記憶體中,不會寫入磁碟。
Python 範例使用 pip install "openai[realtime]>=3.8.0"。
TypeScript 範例使用 npm install openai@^7.10.0 ws。
Ruby 範例使用 gem install openai async-websocket。
使用 Go 時,請執行 go get github.com/openai/openai-go/v3@v3.98.0。
使用 Java 時,請加入 Maven 相依套件 com.openai:openai-java:4.101.0。
這些版本的 Go 和 Java SDK 原生支援 Responses WebSocket。
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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76 import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";
const testLogTool: OpenAI.Responses.FunctionTool = {
type: "function",
name: "search_test_logs",
description: "Search test logs for a query.",
parameters: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
additionalProperties: false,
},
strict: true,
};
const codeSearchTool: OpenAI.Responses.FunctionTool = {
type: "function",
name: "search_code",
description: "Search the codebase for a query.",
parameters: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
additionalProperties: false,
},
strict: true,
};
const openai = new OpenAI();
const ws = new ResponsesWS(openai);
try {
ws.send({
type: "response.create",
model: "gpt-6-astra",
store: false,
input: [
{
type: "message",
role: "user",
content: [
{
type: "input_text",
text:
"Find the flaky test in this run, call the tools you need, " +
"and keep going until you can explain the root cause.",
},
],
},
],
tools: [testLogTool, codeSearchTool],
});
let completed = false;
for await (const event of ws) {
if (event.type === "error") throw event.error;
if (event.type !== "message") continue;
const message = event.message;
if (message.type === "response.completed") {
console.log(JSON.stringify(message.response.output));
completed = true;
break;
}
if (
message.type === "response.failed" ||
message.type === "response.incomplete"
) {
throw new Error(JSON.stringify(message));
}
}
if (!completed) {
throw new Error("Connection closed before the response finished.");
}
} finally {
ws.close();
} 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61 from openai import OpenAI
from openai.types.responses import FunctionToolParam
test_log_tool: FunctionToolParam = {
"type" : "function" ,
"name" : "search_test_logs" ,
"description" : "Search test logs." ,
"parameters" : {
"type" : "object" ,
"properties" : { "query" : { "type" : "string" }},
"required" : [ "query" ],
"additionalProperties" : False ,
},
"strict" : True ,
}
code_search_tool: FunctionToolParam = {
"type" : "function" ,
"name" : "search_code" ,
"description" : "Search source code." ,
"parameters" : {
"type" : "object" ,
"properties" : { "query" : { "type" : "string" }},
"required" : [ "query" ],
"additionalProperties" : False ,
},
"strict" : True ,
}
client = OpenAI()
with client.responses.connect() as connection:
# Use the same typed parameters as client.responses.create(...).
connection.response.create(
model = "gpt-6-astra" ,
store = False ,
input = [
{
"type" : "message" ,
"role" : "user" ,
"content" : [
{
"type" : "input_text" ,
"text" : (
"Find the flaky test in this run, call the tools "
"you need, and keep going until you can explain "
"the root cause."
),
}
],
}
],
tools = [test_log_tool, code_search_tool],
)
for event in connection:
if event.type == "response.completed" :
print (event.response.output)
break
if event.type in { "response.failed" , "response.incomplete" , "error" }:
raise RuntimeError (event.to_json())
else :
raise RuntimeError ( "Connection closed before the response finished." ) 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57 tools := []responses.ToolUnionParam{}
for _, name := range []string{
"search_test_logs",
"search_code",
} {
tools = append(tools, responses.ToolUnionParam{
OfFunction: &responses.FunctionToolParam{
Name: name,
Description: openai.String("Search for a query."),
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"query": map[string]any{
"type": "string",
},
},
"required": []string{
"query",
},
"additionalProperties": false,
},
Strict: openai.Bool(true),
},
})
}
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
Model: "gpt-6-astra",
Store: openai.Bool(false),
Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
OfString: openai.String("Find the flaky test in this run, call the tools you need, and keep going until you can explain the root cause."),
},
Tools: tools,
}); err != nil {
log.Fatal(err)
}
response, err := conn.FinalResponse(ctx)
if err != nil {
log.Fatal(err)
}
if response.Status != responses.ResponseStatusCompleted {
log.Fatalf("Response ended with status %s", response.Status)
}
output := make([]json.RawMessage, 0, len(response.Output))
for _, item := range response.Output {
output = append(output, json.RawMessage(item.RawJSON()))
}
if err := json.NewEncoder(os.Stdout).Encode(output); err != nil {
log.Fatal(err)
} 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
32
33
34
35
36
37
38
39
40 import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.*;
import java.util.*;
var tools = new ArrayList<Tool>();
for (var name : List.of("search_test_logs", "search_code"))
tools.add(
Tool.ofFunction(
FunctionTool.builder()
.name(name)
.description("Search for a query.")
.strict(true)
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties",
JsonValue.from(Map.of("query", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.build()));
try (var conn = client.responses().connect()) {
conn.send(
ResponsesClientEvent.ofResponseCreate(
ResponsesClientEvent.ResponseCreate.builder()
.model("gpt-6-astra")
.store(false)
.input(
"Find the flaky test in this run, call the tools you need, and keep going until you can explain the root cause.")
.tools(tools)
.build()));
var response = conn.finalResponse();
if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
throw new IllegalStateException(
"Response ended with status " + response.status().orElse(null));
System.out.println(response.output());
} 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58 require "async"
require "openai"
require "json"
def wait_for_response(connection)
while (event = connection.receive)
case event.type.to_s
when "response.completed" then return event.response
when "response.failed", "response.incomplete", "error"
raise "Response failed: #{event.to_json}"
end
end
raise "Connection closed before the response finished"
end
test_log_tool = {
type: "function",
name: "search_test_logs",
description: "Search test logs.",
parameters: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
additionalProperties: false
},
strict: true
}
code_search_tool = {
type: "function",
name: "search_code",
description: "Search source code.",
parameters: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
additionalProperties: false
},
strict: true
}
client = OpenAI::Client.new
Sync do |task|
task.with_timeout(120) do
client.responses.connect(request_options: { timeout: 10 }) do |connection|
connection.response.create(
stream_id: "main", model: "gpt-6-astra", store: false,
input: [
{
role: "user",
content: "Find the flaky test in this run, call the tools you need, and keep going until you can explain the root cause."
}
],
tools: [test_log_tool, code_search_tool]
)
puts(JSON.pretty_generate(wait_for_response(connection).output.map(&:to_h)))
end
end
end
如果使用者可能在 GPT-6 模型執行任務期間新增需求,請透過 WebSocket 連線至 Responses API。傳送 response.steer 時,請在 previous_response_id 中填入進行中回應的 ID,並附上新的使用者輸入。繼續讀取後續執行的事件。收到 response.steer.accepted 表示更新已排入佇列。在回合中途調整方向不會變更已傳送至應用程式的輸出,也不會撤銷已開始執行的工具操作。事件流程及工具結果的處理方式請參閱在回合中途調整方向 。
Responses API 是打造更聰明、能力更強的 OpenAI 應用程式的基礎。透過這個 API,開發者可以從單次提示詞進一步建立能持續執行、使用工具並掌握上下文的工作流程,依任務的複雜程度調整做法。請運用本指南中的做法,提升實際部署的效能。