Habilidades | OpenAI API

As habilidades fornecem ao agente instruções reutilizáveis e arquivos de apoio para realizar uma tarefa. Use-as com as ferramentas de shell da Responses API ou disponibilize-as em um sandbox da Agents API.

As instruções a seguir explicam como enviar, anexar e versionar habilidades para as ferramentas de shell da Responses API. As sessões da Agents API encontram as habilidades nos diretórios do sandbox.

A Responses API oferece dois modos de execução de habilidades: local e hospedado em contêineres. Para executar código na sua máquina, use o modo de execução local da ferramenta de shell.

O que é uma habilidade

Uma habilidade é um diretório de arquivos com um manifesto SKILL.md que contém um cabeçalho de metadados e instruções. As habilidades reúnem instruções modulares que você pode usar para formalizar processos e convenções, desde guias de estilo da empresa até fluxos de trabalho com várias etapas. As habilidades enviadas usam pacotes com controle de versões.

As habilidades são compatíveis com o padrão aberto de habilidades de agentes.

Exemplo de 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.

Ao descobrir uma habilidade, o modelo vê o nome e a descrição dela. Escreva uma descrição que explique o que a habilidade faz e quando usá-la. Por exemplo, “Revise contratos de fornecedores e marque as alterações com base nas cláusulas alternativas” dá ao modelo mais contexto do que “Ajuda com questões jurídicas”.

Mantenha as instruções principais em SKILL.md e inclua links para os arquivos de apoio conforme necessário:

review-pr/
├── SKILL.md
├── references/
│   └── review-guidelines.md
├── scripts/
│   └── check-changes.sh
└── assets/
    └── review-template.md

Use references/ para materiais de referência, scripts/ para ações repetíveis e assets/ para modelos reutilizáveis.

Criar uma habilidade

Você pode enviar um diretório como dados de formulário multipart ou enviar um arquivo .zip que contenha uma única pasta no nível superior.

Opção 1: Envio de diretório (multipart)

Envie várias partes files[]. Cada parte inclui o caminho do arquivo dentro da mesma pasta de nível superior.

Criar uma habilidade (multipart)

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'

Opção 2: Envio de arquivo zip

Compacte a pasta de nível superior e envie o arquivo zip.

Criar uma habilidade (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'

Aguardar a disponibilidade de uma versão enviada

Logo após o envio, uma consulta à nova versão pode retornar 404 por um breve período, até que a versão fique disponível. Antes de anexá-la a um contêiner ou a uma sessão Live, consulte-a com GET /v1/skills/{skill_id}/versions/{version}. Se a consulta retornar 404 logo após um envio bem-sucedido, aguarde um breve intervalo e tente novamente, respeitando um tempo limite para as tentativas. Quando a consulta for bem-sucedida, use a string de versão retornada na referência à habilidade.

Usar habilidades com o shell hospedado

Para montar habilidades em um ambiente de shell hospedado, anexe-as por meio de tools[].environment.skills ao chamar a ferramenta de shell.

Usar habilidades no shell hospedado

curl

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)

Como orientar o modelo no prompt

Depois que a habilidade é montada, o modelo pode decidir quando usá-la. Se quiser um comportamento mais determinístico, dê ao modelo a instrução explícita “use a habilidade <skill name>” quando for apropriado.

Usar habilidades no modo de shell local

As habilidades também funcionam no modo de shell local, mas o shell local e o shell hospedado aceitam formatos diferentes para anexá-las.

O shell hospedado aceita anexos skill_reference para habilidades já enviadas, inclusive habilidades selecionadas e versões específicas.
O shell local não aceita anexos skill_reference. Forneça os arquivos da habilidade por meio de caminhos locais no ambiente de execução que você controla.

Consulte o guia do shell para obter detalhes sobre a execução local.

O exemplo em JavaScript requer o Node.js e o daemon do Docker em execução. Salve o adaptador do Docker como support/local-skill-sandbox.mjs e o exemplo como tools/skills/local-shell.mjs para que a importação relativa funcione. Defina OPENAI_API_KEY, instale o SDK, baixe a versão da imagem fixada pelo adaptador e execute o exemplo a partir do diretório que contém support e tools:

123npm install openai
docker pull "$(node --input-type=module -e 'import { sandboxImage } from "./support/local-skill-sandbox.mjs"; console.log(sandboxImage)')"
node tools/skills/local-shell.mjs

As funções auxiliares do adaptador têm as seguintes responsabilidades:

Função auxiliar	Responsabilidade do aplicativo
`withLocalSkillSandbox(name, workflow)`	Criar um ambiente Python isolado que contenha `/workspace/skills/csv-insights/SKILL.md` e `/workspace/reports.csv`, chamar `workflow` com um `AbortSignal` e remover o ambiente quando o fluxo de trabalho terminar.
`executeShellCall(name, call, signal)`	Executar os comandos solicitados nesse ambiente e retornar um `shell_call_output` com o `call_id` original, stdout, stderr e o resultado da execução (código de saída ou tempo limite excedido).
`readSkillReport(name, signal)`	Ler o arquivo `/workspace/report.md` gerado no ambiente, limitando a quantidade de dados lidos.

O adaptador deve impor prazos de execução e limites para o volume de saída. No exemplo, os comandos gerados são executados dentro do ambiente isolado.

Usar habilidades no modo de shell local

curl

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) => {
  const client = new OpenAI();
  /** @type {OpenAI.Responses.ResponseCreateParamsNonStreaming} */
  const params = {
    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

Para usar habilidades na Agents API, coloque os diretórios das habilidades no sandbox e registre os diretórios pai em environment.capability_directories ao criar a sessão. Esses diretórios pai são chamados de diretórios de capacidades. O harness os usa para descobrir habilidades. Essa configuração dispensa o formato de anexo skill_reference do shell hospedado.

Por exemplo, coloque no sandbox uma habilidade de revisão de contratos e outra de revisão de pull requests:

/workspace/capabilities/
├── legal/
│   └── contract-redline/
│       ├── SKILL.md
│       └── references/
│           └── fallback-clauses.md
└── engineering/
    └── review-pr/
        ├── SKILL.md
        └── references/
            └── review-guidelines.md

Use esta configuração de ambiente na solicitação de criação da sessão:

12345678910{
  "environment": {
    "type": "self_hosted",
    "workspace_directory": "/workspace",
    "capability_directories": [
      "/workspace/capabilities/legal",
      "/workspace/capabilities/engineering"
    ]
  }
}

Os diretórios de capacidades devem atender aos seguintes requisitos:

Os caminhos devem apontar para diretórios dentro do sandbox.
Os caminhos devem ser absolutos e únicos e não podem conter os segmentos . ou ...
Cada sessão pode registrar até 32 diretórios de capacidades.
Os diretórios já devem existir no ambiente.

Assim que o sandbox fica disponível, o harness procura arquivos SKILL.md nesses diretórios e adiciona ao contexto o nome e a descrição de cada habilidade encontrada. O modelo pode selecionar as habilidades relevantes e ler suas instruções completas e seus arquivos de apoio.

Consulte Configuração do agente para configurar a sessão e Conectar um sandbox para configurar o ambiente de execução. Revise as habilidades e seus arquivos de apoio antes de disponibilizá-los ao agente e siga as orientações de segurança do sandbox.

Habilidades no prompt do usuário

Para as ferramentas de shell da Responses API, a plataforma adiciona os campos name, description e path de cada habilidade disponível ao contexto do prompt do usuário. Assim, o modelo sabe que a habilidade existe.

O modelo usa esses metadados para decidir se deve usar a habilidade. Se decidir usá-la, o modelo usa path para ler as instruções completas em Markdown no arquivo SKILL.md.

As instruções da habilidade fazem parte do prompt do usuário, e não do prompt do sistema. Por isso, recebem a mesma prioridade que as demais instruções fornecidas pelo usuário. Para controlar a seleção explicitamente, você ainda pode dar ao modelo a instrução “use a habilidade <skill name>”.

Limites e validação

A identificação do arquivo SKILL.md não diferencia maiúsculas de minúsculas.
Cada pacote de habilidade deve conter exatamente um arquivo skill.md/SKILL.md.
A validação do cabeçalho de metadados da habilidade segue a especificação de habilidades de agentes.
O tamanho máximo do arquivo zip para envio é de 50 MB.
Cada versão de uma habilidade pode conter no máximo 500 arquivos.
O tamanho máximo de cada arquivo descompactado é de 25 MB.

Segurança no uso de habilidades com acesso à rede

Inspecione todas as habilidades usadas com a Responses API. As habilidades introduzem riscos de segurança, como a exfiltração de dados por injeção de prompt. Leia com atenção a seção Riscos e segurança abaixo antes de usar esta ferramenta.

Controle de versões e gerenciamento

Referências a versões

default_version indica a versão usada quando nenhuma versão é informada.
latest_version aponta para a versão enviada mais recentemente.
skill_reference.version aceita uma string de versão, como "2" ou "latest".
default_version também exige uma string ao ser atualizado.

Criar uma nova versão

Criar uma nova versão da habilidade

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'

Definir a versão padrão

Definir a versão padrão de uma habilidade

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"}'

Regras de exclusão

Para excluir a versão padrão, primeiro defina outra versão como padrão.
Excluir a última versão restante também exclui a habilidade.
Excluir uma habilidade remove todas as suas versões.

Habilidades selecionadas

A OpenAI mantém um conjunto de habilidades próprias que você pode referenciar pelo identificador (por exemplo, openai-spreadsheets).

Referenciar uma habilidade selecionada

{ "type": "skill_reference", "skill_id": "openai-spreadsheets", "version": "latest" }

Habilidades incorporadas

Se não quiser criar uma habilidade hospedada, você pode incluir um pacote zip codificado em base64 diretamente no array skills do ambiente.

Incorporar um pacote de habilidade

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"'"
        }
      }
    ]
  }'

Riscos e segurança

É importante inspecionar todas as habilidades usadas com a Responses API. As habilidades introduzem riscos de segurança, como a exfiltração de dados por injeção de prompt.

Ao usar habilidades com acesso à rede, leia com atenção a seção sobre riscos e segurança do acesso à rede.

Trate as habilidades como código e instruções com privilégios elevados

O conteúdo de uma habilidade pode influenciar o planejamento, o uso de ferramentas e a execução de comandos. Ao revisar uma habilidade, trate seu conteúdo como potencialmente não confiável até que o desenvolvedor o valide.

Não exponha um repositório aberto de habilidades aos usuários finais

Evite criar produtos que permitam aos usuários finais explorar livremente um catálogo aberto de habilidades, selecionar qualquer uma delas ou anexá-la. Isso aumenta consideravelmente o risco de:

Injeção de prompt e contorno de políticas por meio de instruções maliciosas no arquivo SKILL.md.
Exfiltração de dados ou ações destrutivas desencadeadas por automações que não passaram por revisão.

Integre as habilidades no desenvolvimento do produto

O desenvolvedor deve inspecionar e integrar as habilidades. Só então deve disponibilizá-las aos usuários finais por meio de funcionalidades com escopo delimitado. Na prática:

Associe as habilidades a fluxos de trabalho ou casos de uso específicos do produto.
Impeça que os usuários finais selecionem habilidades arbitrariamente.
Exija aprovação explícita e verifique o cumprimento das políticas aplicáveis antes de permitir ações de escrita ou de alto impacto.

Exija aprovação para ações sensíveis

Para fluxos de trabalho que podem realizar ações de escrita ou de alto impacto, exija aprovação explícita antes da execução.

Valide os requisitos de residência de dados e de retenção

A Responses API oferece dois modos de execução de habilidades: local e hospedado em contêineres. As habilidades hospedadas seguem o mesmo ciclo de vida dos contêineres do shell hospedado. As habilidades montadas e os arquivos do contêiner ficam disponíveis enquanto ele está ativo e são descartados quando ele expira ou é excluído. Se quiser que toda a execução ocorra na infraestrutura que você gerencia, use o modo de shell local. Para os sandboxes da Agents API, consulte Ciclo de vida do sandbox. Saiba mais sobre nossos controles de dados.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso