智慧體技能為智慧體提供執行特定任務時可重複使用的指示與輔助檔案。你可以搭配 Responses API 的 Shell 工具使用技能,也可以將技能放入 Agents API 沙盒供智慧體使用。
以下關於上傳、附加技能與版本管理的說明適用於 Responses API 的 Shell 工具。Agents API 工作階段會從沙盒中的目錄探索技能。
Responses API 支援兩種技能執行方式:在本機執行,或在託管容器中執行。若要在自己的機器上執行程式碼,請使用 Shell 工具的本機執行模式。
技能是一個目錄,其中的 SKILL.md 資訊清單由檔案開頭的中繼資料和指示組成。你可以用技能將流程與慣例寫成模組化指示,例如公司的風格指南或多步驟工作流程。上傳的技能以套件形式儲存,並按版本管理。
技能與開放的智慧體技能標準相容。
1
2
3
4
5
6---
name: basic-math
description: Add or multiply numbers.
---
Use this skill when you need a quick sum or product of numbers.
探索技能時,模型會看到技能的名稱與說明。撰寫說明時,請交代技能的用途與適用時機。例如,「審閱供應商合約,並依據備用條款標註修訂內容」比「協助處理法律事務」更能讓模型判斷何時該使用這項技能。
將主要指示寫在 SKILL.md 中,並視需要加入輔助檔案的連結:
review-pr/
├── SKILL.md
├── references/
│ └── review-guidelines.md
├── scripts/
│ └── check-changes.sh
└── assets/
└── review-template.md
將背景資料放在 references/,將可重複執行的操作指令碼放在 scripts/,並將可重複使用的範本放在 assets/。
你可以使用多部分表單資料上傳目錄,也可以上傳只包含一個頂層資料夾的 .zip 檔案。
上傳多個 files[] 部分。每個部分都須包含檔案在同一個頂層資料夾內的路徑。
1
2
3
4curl -X POST 'https://api.openai.com/v1/skills' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'files[]=@./basic_math/SKILL.md;filename=basic_math/SKILL.md;type=text/markdown' \
-F 'files[]=@./basic_math/calculate.py;filename=basic_math/calculate.py;type=text/plain'
將頂層資料夾壓縮成 ZIP 檔案後上傳。
1
2
3curl -X POST 'https://api.openai.com/v1/skills' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'files=@./basic_math.zip;type=application/zip'
剛上傳的版本可能需要一點時間才可使用,在此期間,擷取該版本的請求可能會傳回 404。將版本附加至容器或 Live 工作階段之前,請先使用 GET /v1/skills/{skill_id}/versions/{version} 擷取該版本。如果上傳成功後立即擷取卻收到 404,請設定逾時期限,並在短暫等候後重試。擷取成功後,請在技能參照中使用傳回的版本字串。
若要在託管 Shell 環境中掛載技能,請在呼叫 Shell 工具時透過 tools[].environment.skills 附加技能。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19curl -L 'https://api.openai.com/v1/responses' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [
{
"type": "shell",
"environment": {
"type": "container_auto",
"skills": [
{ "type": "skill_reference", "skill_id": "<skill_id>" },
{ "type": "skill_reference", "skill_id": "<skill_id>", "version": "2" }
]
}
}
],
"input": "Use the skills to add 144 and 377, then compute triangle area with base 9 height 13."
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6-astra",
tools: [
{
type: "shell",
environment: {
type: "container_auto",
skills: [
{ type: "skill_reference", skill_id: "<skill_id>" },
{ type: "skill_reference", skill_id: "<skill_id>", version: "2" },
],
},
},
],
input:
"Use the skills to add 144 and 377, then compute triangle area with base 9 height 13.",
});
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
21
22response = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "shell",
"environment": {
"type": "container_auto",
"skills": [
{"type": "skill_reference", "skill_id": "<skill_id>"},
{
"type": "skill_reference",
"skill_id": "<skill_id>",
"version": "2",
},
],
},
}
],
input="Use the skills to add 144 and 377, then compute triangle area with base 9 height 13.",
)
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
30package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{
Environment: responses.FunctionShellToolEnvironmentUnionParam{OfContainerAuto: &responses.ContainerAutoParam{
Skills: []responses.ContainerAutoSkillUnionParam{
{OfSkillReference: &responses.SkillReferenceParam{SkillID: "<skill_id>"}},
{OfSkillReference: &responses.SkillReferenceParam{SkillID: "<skill_id>", Version: openai.String("2")}},
},
}},
}}
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the skills to add 144 and 377, then compute triangle area with base 9 height 13.")},
})
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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;
String skillId = "<skill_id>";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Use the skills to add 144 and 377, then compute a triangle area with base 9 and height 13.")
.putAdditionalBodyProperty(
"tools",
JsonValue.from(
List.of(
Map.of(
"type",
"shell",
"environment",
Map.of(
"type",
"container_auto",
"skills",
List.of(
Map.of("type", "skill_reference", "skill_id", skillId),
Map.of(
"type", "skill_reference",
"skill_id", skillId,
"version", "2")))))))
.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
23
24
25
26
27
28require "openai"
client = OpenAI::Client.new
response = client.responses.create(
model: "gpt-6-astra",
input: "Use the skills to add 144 and 377, then compute a triangle area with base 9 and height 13.",
tools: [
{
type: :shell,
environment: {
type: :container_auto,
skills: [
{
type: :skill_reference,
skill_id: "<skill_id>"
},
{
type: :skill_reference,
skill_id: "<skill_id>",
version: "2"
}
]
}
}
]
)
puts(response.output_text)
技能掛載後,模型可以自行決定何時使用。若要讓行為更可預測,可以在適當時機明確指示模型「使用 <skill name> 技能」。
本機 Shell 模式也支援技能,但本機 Shell 與託管 Shell 環境接受的技能附件格式不同。
- 託管 Shell 環境支援以
skill_reference 附加已上傳的技能,也支援精選技能及明確指定的版本。
- 本機 Shell 不支援
skill_reference 附件。請透過你所管理的執行環境中的本機檔案路徑提供技能檔案。
如需本機 Shell 的執行細節,請參閱 Shell 指南。
執行 TypeScript 範例需要 Node.js 22.6 或更新版本,且 Docker 常駐程式必須正在執行。請將 Docker 配接器儲存為 support/local-skill-sandbox.mjs,並將範例儲存為 tools/skills/local-shell.mts,以便範例透過相對路徑匯入配接器。
設定 OPENAI_API_KEY 後,請在包含 support 和 tools 的目錄中安裝 SDK、下載配接器指定版本的映像檔,然後執行範例:
123npm install openai
docker pull "$(node --input-type=module -e 'import { sandboxImage } from "./support/local-skill-sandbox.mjs"; console.log(sandboxImage)')"
node --experimental-strip-types tools/skills/local-shell.mts
配接器的各個輔助函式負責下列工作:
| 輔助函式 |
應用程式負責的工作 |
withLocalSkillSandbox(name, workflow) |
建立包含 /workspace/skills/csv-insights/SKILL.md 和 /workspace/reports.csv 的隔離 Python 環境,呼叫 workflow 並傳入 AbortSignal,在工作流程結束時移除該環境。 |
executeShellCall(name, call, signal) |
在該環境中執行所要求的指令,並傳回 shell_call_output,其中包含原始的 call_id、標準輸出、標準錯誤輸出,以及指令結束或逾時的結果。 |
readSkillReport(name, signal) |
從該環境讀取產生的 /workspace/report.md,並限制讀取的資料量。 |
配接器必須限制指令的執行時間與輸出量。範例只會在隔離的執行環境中執行產生的指令。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22curl -L 'https://api.openai.com/v1/responses' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [
{
"type": "shell",
"environment": {
"type": "local",
"skills": [
{
"name": "csv-insights",
"description": "Summarize CSV files and produce a markdown report.",
"path": "<path-to-skill-folder>"
}
]
}
}
],
"input": "Use the csv-insights skill and run locally to summarize today\'s CSV reports in this repo."
}'
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
56import { randomUUID } from "node:crypto";
import OpenAI from "openai";
import {
withLocalSkillSandbox,
executeShellCall,
readSkillReport,
} from "../../support/local-skill-sandbox.mjs";
// Requires Docker. The application-owned helper prepares a disposable Python
// sandbox with the skill and CSV files; generated commands run only inside it.
const name = "node-skill-" + randomUUID();
await withLocalSkillSandbox(name, async (signal: AbortSignal) => {
const client = new OpenAI();
/** @type {OpenAI.Responses.ResponseCreateParamsNonStreaming} */
const params: OpenAI.Responses.ResponseCreateParamsNonStreaming = {
model: "gpt-6-astra",
tools: [
{
type: "shell",
environment: {
type: "local",
skills: [
{
name: "csv-insights",
description: "Summarize CSV files and produce a markdown report.",
path: "/workspace/skills/csv-insights",
},
],
},
},
],
input:
"Use the csv-insights skill and run locally to summarize /workspace/reports.csv. Read the skill instructions, write /workspace/report.md, and include the total in your final answer.",
};
for (let turn = 0; turn <= 8; turn++) {
const response = await client.responses.create(params, { signal });
if (response.status !== "completed")
throw new Error(`Response ended with status ${response.status}`);
const results = [];
for (const item of response.output) {
if (item.type !== "shell_call") continue;
if (turn === 8)
throw new Error("Shell workflow exceeded eight tool turns");
results.push(await executeShellCall(name, item, signal));
}
if (results.length === 0) {
console.log(response.output_text);
console.log("Report:\n" + (await readSkillReport(name, signal)));
return;
}
params.previous_response_id = response.id;
params.input = results;
}
throw new Error("Shell workflow exceeded eight turns");
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22response = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "shell",
"environment": {
"type": "local",
"skills": [
{
"name": "csv-insights",
"description": "Summarize CSV files and produce a markdown report.",
"path": "<path-to-skill-folder>",
}
],
},
}
],
input="Use the csv-insights skill and run locally to summarize today's CSV reports in this repo.",
)
# Execute returned shell calls locally and submit their shell_call_output to continue.
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// The surrounding program prepares an isolated sandbox with the skill files.
client := openai.NewClient()
tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{
Environment: responses.FunctionShellToolEnvironmentUnionParam{
OfLocal: &responses.LocalEnvironmentParam{
Skills: []responses.LocalSkillParam{{
Name: "csv-insights",
Description: "Summarize CSV files and produce a markdown report.",
Path: "/workspace/skills/csv-insights",
}},
},
},
}}
params := responses.ResponseNewParams{
Model: "gpt-6-astra",
Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(
"Use the csv-insights skill and run locally to summarize /workspace/reports.csv. Read the skill instructions, write /workspace/report.md, and include the total in your final answer.")},
}
for turn := 0; turn <= 8; turn++ {
response, err := client.Responses.New(ctx, params)
if err != nil {
return err
}
if response.Status != responses.ResponseStatusCompleted {
return fmt.Errorf("response ended with status %s", response.Status)
}
results := responses.ResponseInputParam{}
for _, item := range response.Output {
if item.Type != "shell_call" {
continue
}
if turn == 8 {
return fmt.Errorf("shell workflow exceeded eight tool turns")
}
result, err := executeShellCall(ctx, name, item.AsShellCall())
if err != nil {
return err
}
results = append(results, result)
}
if len(results) == 0 {
fmt.Println(response.OutputText())
// Read the artifact without executing generated code outside the container.
report, err := readReport(ctx, name)
if err != nil {
return fmt.Errorf("read generated report: %w", err)
}
fmt.Printf("Report:\n%s\n", report)
return nil
}
params.PreviousResponseID = openai.String(response.ID)
params.Input = responses.ResponseNewParamsInputUnion{OfInputItemList: results}
}
return fmt.Errorf("shell workflow exceeded eight turns")
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
38import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;
String skillPath = "<path-to-skill-folder>";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("Use the csv-insights skill to summarize today's CSV reports.")
.putAdditionalBodyProperty(
"tools",
JsonValue.from(
List.of(
Map.of(
"type",
"shell",
"environment",
Map.of(
"type",
"local",
"skills",
List.of(
Map.of(
"name", "csv-insights",
"description",
"Summarize CSV files and produce a Markdown report.",
"path", skillPath)))))))
.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
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
52require "openai"
require "open3"
require "securerandom"
# LocalSkillSandbox is the application-owned Docker executor defined in this
# complete example. It prepares the skill files, bounds execution, and cleans up.
def run_local_skill(name)
sandbox = LocalSkillSandbox.new(name)
begin
# Reserve teardown before creation, even if Docker creation is interrupted.
sandbox.prepare
client = OpenAI::Client.new(max_retries: 0)
params = {
model: "gpt-6-astra",
input: "Use the csv-insights skill and run locally to summarize /workspace/reports.csv. Read the skill instructions, write /workspace/report.md, and include the total in your final answer.",
tools: [
{
type: :shell,
environment: {
type: :local,
skills: [
{
name: "csv-insights",
description: "Summarize CSV files and produce a Markdown report.",
path: "/workspace/skills/csv-insights"
}
]
}
}
]
}
9.times do |turn|
response = client.responses.create(**params, request_options: { timeout: sandbox.remaining })
raise "Response did not complete" unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED
calls = response.output.grep(OpenAI::Models::Responses::ResponseFunctionShellToolCall)
if calls.empty?
puts(response.output_text)
puts("Report:\n#{sandbox.report}")
return response
end
raise "Shell workflow exceeded eight tool turns" if turn == 8
params[:input] = calls.map { |call| sandbox.execute(call) }
params[:previous_response_id] = response.id
end
ensure
sandbox.close
end
end
run_local_skill("ruby-skill-#{SecureRandom.hex(8)}")
若要在 Agents API 中使用技能,請將技能目錄放入沙盒,並在建立工作階段時,於 environment.capability_directories 中註冊這些目錄的上層目錄。這些上層目錄稱為能力目錄。任務執行框架會從這些目錄探索技能。這種設定不使用託管 Shell 環境的 skill_reference 附件格式。
例如,你可以在沙盒中放入審閱合約和審查 Pull Request 的技能:
/workspace/capabilities/
├── legal/
│ └── contract-redline/
│ ├── SKILL.md
│ └── references/
│ └── fallback-clauses.md
└── engineering/
└── review-pr/
├── SKILL.md
└── references/
└── review-guidelines.md
在建立工作階段的請求中使用下列環境設定:
12345678910{
"environment": {
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": [
"/workspace/capabilities/legal",
"/workspace/capabilities/engineering"
]
}
}
能力目錄須符合下列要求:
- 路徑必須指向沙盒內的目錄。
- 每個路徑都必須是絕對路徑,不得重複,也不得包含
. 或 .. 路徑區段。
- 每個工作階段最多可註冊 32 個能力目錄。
- 目錄必須已存在於環境中。
沙盒就緒後,任務執行框架會在這些目錄中搜尋 SKILL.md 檔案,並將找到的每項技能的名稱與說明加入上下文。模型可以選擇相關技能,並讀取完整指示與輔助檔案。
如需工作階段的設定方式,請參閱智慧體設定。如需執行環境的相關資訊,請參閱連接沙盒。將技能提供給智慧體使用前,請先審查技能及其輔助檔案,並遵循沙盒安全指引。
使用 Responses API 的 Shell 工具時,平台會將每項可用技能的 name、description 和 path 加入使用者提示詞的上下文,讓模型知道有哪些技能可用。
模型會根據這些中繼資料決定是否呼叫技能。如果模型決定呼叫某項技能,就會使用 path 從 SKILL.md 讀取完整的 Markdown 指示。
技能指示屬於使用者提示詞輸入,而非系統提示詞輸入,因此其優先順序與使用者提供的其他指示相同。若要明確指定技能,你仍可指示模型「使用 <skill name> 技能」。
- 比對
SKILL.md 檔名時不區分大小寫。
- 每個技能套件必須有且只能有一個
skill.md/SKILL.md 檔案。
- 技能檔案開頭的中繼資料會依照智慧體技能規格進行驗證。
- 上傳的 ZIP 檔案大小上限為
50 MB。
- 每個技能版本最多可包含
500 個檔案。
- 單一檔案解壓縮後的大小上限為
25 MB。
請檢查所有搭配 Responses API 使用的技能。技能會帶來安全風險,例如攻擊者可能透過提示注入竊取資料。使用此工具前,請仔細閱讀下方的風險與安全一節。
- 未指定版本時,會使用
default_version。
latest_version 會指向最新上傳的版本。
skill_reference.version 接受版本字串,例如 "2" 或 "latest"。
- 更新
default_version 時也必須使用字串。
1
2
3curl -X POST 'https://api.openai.com/v1/skills/<skill_id>/versions' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'files=@./geometry.zip;type=application/zip'
1
2
3
4curl -X POST 'https://api.openai.com/v1/skills/<skill_id>' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{"default_version": "2"}'
- 無法刪除目前的預設版本。請先將其他版本設為預設版本。
- 刪除僅存的版本時,技能也會一併刪除。
- 刪除技能時,會一併移除所有版本。
OpenAI 維護了一組第一方技能,你可以透過 ID(例如 openai-spreadsheets)參照這些技能。
{ "type": "skill_reference", "skill_id": "openai-spreadsheets", "version": "latest" }
如果不想建立託管技能,可以將 ZIP 套件以 base64 編碼後,直接內嵌在環境的 skills 陣列中。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20INLINE_ZIP=$(base64 -i ./basic_math.zip)
curl -L 'https://api.openai.com/v1/containers' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"name": "inline-skill-container",
"skills": [
{
"type": "inline",
"name": "basic_math",
"description": "Add or multiply numbers.",
"source": {
"type": "base64",
"media_type": "application/zip",
"data": "'"$INLINE_ZIP"'"
}
}
]
}'
請務必檢查所有搭配 Responses API 使用的技能。技能會帶來安全風險,例如攻擊者可能透過提示注入竊取資料。
如果使用技能時也開放網路存取,請仔細閱讀網路存取的風險與安全注意事項。
技能內容可能影響模型如何規劃、使用工具與執行指令。開發人員驗證技能之前,應將所有技能視為可能不可信的輸入加以審查。
設計消費者產品時,應避免讓終端使用者自由瀏覽開放目錄,或從中任意選擇、附加技能。這類設計會大幅提高下列風險:
- 攻擊者透過惡意 SKILL.md 指示進行提示注入或規避政策。
- 未經審查的自動化流程導致資料外洩或觸發破壞性操作。
開發人員應先檢查並整合技能,再透過範圍明確的產品功能提供給終端使用者。具體做法如下:
- 將技能對應至特定的產品工作流程或使用情境。
- 防止終端使用者任意選擇技能。
- 寫入或影響重大的操作必須先取得明確核准並通過政策檢查,才能執行。
如果工作流程可以執行寫入或影響重大的操作,請要求在執行前取得明確核准。
Responses API 支援兩種技能執行方式:在本機執行,或在託管容器中執行。託管技能的容器生命週期與託管 Shell 環境相同。容器運作期間,已掛載的技能和容器檔案都可使用。容器到期或遭刪除時,這些技能和檔案也會一併移除。如果你希望所有操作都在自己管理的基礎架構上執行,請使用本機 Shell 模式。如需瞭解 Agents API 沙盒,請參閱沙盒生命週期。如需瞭解我們如何控管資料,請參閱資料控制措施。