Habilidades | OpenAI API

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

As instruções de envio, vinculação e versionamento abaixo se aplicam às ferramentas de shell da API Responses. As sessões da API de Agentes descobrem habilidades nos diretórios de seu sandbox.

A API Responses oferece suporte a habilidades em duas modalidades: execução local e execução hospedada em contêineres. Para executar código na sua própria 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 (metadados de cabeçalho + instruções). Habilidades são 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 versionados.

As habilidades são compatíveis com o padrão aberto Agent Skills.

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.

Durante a descoberta de habilidades, o modelo vê o nome e a descrição de cada habilidade. Escreva uma descrição que explique tanto o que a habilidade faz quanto quando usá-la. Por exemplo, "Revise contratos com fornecedores e marque as alterações usando as cláusulas alternativas" fornece ao modelo um contexto mais útil do que "Ajuda com questões jurídicas".

Mantenha as instruções principais em SKILL.md e inclua links para 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 material de referência, scripts/ para ações repetíveis e assets/ para modelos reutilizáveis.

Crie 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 dentro de uma única pasta no nível superior.

Crie 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 em formato zip e envie o arquivo zip.

Crie 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'

Use 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 shell.

Use 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)

Comportamento em resposta aos prompts

Depois que uma habilidade é montada, o modelo pode decidir quando usá-la. Se quiser um comportamento mais determinístico, instrua explicitamente o modelo a "usar a habilidade <skill name>" quando for apropriado.

Use habilidades com o modo de shell local

As habilidades também funcionam com o modo de shell local, mas o shell local e o shell hospedado não aceitam os mesmos formatos de anexos de habilidades.

O shell hospedado oferece suporte a anexos skill_reference enviados, incluindo habilidades selecionadas por curadoria e versões explícitas.
O shell local não oferece suporte a anexos skill_reference. Em vez disso, forneça arquivos de habilidades a partir de caminhos de arquivos locais no ambiente de execução que você controla.

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

Use 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
26import OpenAI from "openai";

const client = new OpenAI();

const response = await 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.",
});

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
21response = 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.",
)

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
31package 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{OfLocal: &responses.LocalEnvironmentParam{
			Skills: []responses.LocalSkillParam{{
				Name:        "csv-insights",
				Description: "Summarize CSV files and produce a markdown report.",
				Path:        "<path-to-skill-folder>",
			}},
		}},
	}}
	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 csv-insights skill and run locally to summarize today's CSV reports in this repo.")},
	})
	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
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
24require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use the csv-insights skill to summarize today's CSV reports.",
  tools: [
    {
      type: :shell,
      environment: {
        type: :local,
        skills: [
          {
            name: "csv-insights",
            description: "Summarize CSV files and produce a Markdown report.",
            path: "<path-to-skill-folder>"
          }
        ]
      }
    }
  ]
)

puts(response.output_text)

API de Agentes

Para usar habilidades na API de Agentes, coloque os diretórios das habilidades no sandbox e registre os diretórios pai em environment.capability_directories ao criar a sessão. Eles são chamados de diretórios de capacidades. O harness os usa para descobrir habilidades; essa configuração não usa o formato de vinculação skill_reference do shell hospedado.

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

/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 requisiçã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 de caminho . ou ...
Uma 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 descoberta. O modelo pode selecionar as habilidades relevantes e ler suas instruções completas e seus arquivos de apoio.

Consulte Configuração de agentes para configurar a sessão e Conecte um sandbox para saber mais sobre 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 API Responses, a plataforma adiciona name, description e path de cada habilidade disponível ao contexto do prompt do usuário, para que o modelo saiba que a habilidade existe.

O modelo decide se deve invocar uma habilidade com base nesses metadados. Se invocar uma habilidade, ele usa path para ler as instruções completas em Markdown do arquivo SKILL.md.

As instruções das habilidades são entradas do prompt do usuário (não do prompt do sistema), portanto recebem a mesma prioridade que outras instruções fornecidas pelo usuário. Para ter controle explícito, você ainda pode instruir o modelo a "usar a habilidade <skill name>".

Limites e validação

A identificação do arquivo SKILL.md não diferencia maiúsculas de minúsculas.
É permitido exatamente um arquivo skill.md/SKILL.md em um pacote de habilidade.
A validação dos metadados de cabeçalho da habilidade segue a especificação de habilidades de agentes.
O tamanho máximo de um arquivo zip para envio é 50 MB.
O número máximo de arquivos por versão de habilidade é 500.
O tamanho máximo de um arquivo descompactado é 25 MB.

Segurança com acesso à rede

É muito importante inspecionar qualquer habilidade usada com a Responses API. As habilidades introduzem riscos de segurança, como exfiltração de dados por injeção de prompt. Leia atentamente a seção Riscos e segurança abaixo antes de usar esta ferramenta.

Versionamento e gerenciamento

Ponteiros de versão

default_version é usado quando uma versão não é fornecida.
latest_version aponta para o envio mais recente.
skill_reference.version aceita um número inteiro ou "latest".

Crie uma nova versão

Crie 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'

Defina a versão padrão

Defina 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

Não é possível excluir a versão padrão; primeiro, defina outra versão como padrão.
Excluir a última versão restante exclui a habilidade.
Excluir uma habilidade remove todas as suas versões em cascata.

Habilidades com curadoria

A OpenAI mantém um conjunto de habilidades próprias que podem ser referenciadas por ID (por exemplo, openai-spreadsheets).

Referencie uma habilidade com curadoria

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

Habilidades embutidas

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

Inclua um pacote de habilidade diretamente

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 qualquer Habilidade usada com a Responses API. Habilidades introduzem riscos de segurança, como exfiltração de dados por injeção de prompt.

Para Habilidades usadas com acesso à rede, revise com atenção a seção de riscos e segurança sobre acesso à rede.

Trate Habilidades como código e instruções com privilégios

O conteúdo de uma Habilidade pode influenciar o planejamento, o uso de ferramentas e a execução de comandos. Toda Habilidade deve ser revisada como uma entrada potencialmente não confiável até ser validada pelo desenvolvedor.

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

Evite projetar produtos em que usuários finais possam navegar, selecionar ou anexar livremente quaisquer Habilidades de um catálogo aberto. Isso aumenta significativamente o risco de:

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

Integre Habilidades no nível do desenvolvedor

As Habilidades devem ser inspecionadas e integradas pelo desenvolvedor e, depois, disponibilizadas aos usuários finais apenas por meio de experiências de produto com escopo delimitado. Na prática:

Associe Habilidades a fluxos de trabalho/casos de uso específicos do produto.
Impeça que usuários finais selecionem Habilidades arbitrariamente.
Condicione ações de escrita ou de alto impacto à aprovação explícita e a verificações de políticas.

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

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

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

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

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog