智能体技能为智能体提供完成特定任务所需的可复用指令和配套文件。您可以在 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.2-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.2-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.2-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.2-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.2-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.2-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.2-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.2-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.2-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.2-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.2-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.2-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" }
如果您不想创建托管技能,可以将经过 Base64 编码的 ZIP 技能包直接放入环境的 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 沙盒,请参阅沙盒生命周期。您还可以进一步了解我们的数据控制措施。