Skills

Uma skill tem nome, descrição, instruções (body) e gatilhos (matcher). Quando a mensagem contém uma das any_keywords (sem diferenciar acentos e maiúsculas), a skill entra no contexto. Uma palavra de probe_keywords sem acerto registra um quase acerto para revisão. O agente usa só as skills de skill_ids na versão e lê referências com a ferramenta skills.read. Uma skill não concede ferramentas: o que o agente pode fazer continua definido em tool_ids.

A versão publicada do agente congela quais skills ele usa (skill_ids), não o conteúdo delas: uma versão nova de conteúdo vale nas próximas respostas de todos os agentes em operação (ativos, não pausados) que incluem a skill. No painel, salvar pede a confirmação "Aplicar a N agentes em operação". Pela API não há confirmação: a resposta traz affected_agents, e a versão guarda a mesma lista no histórico.

Biblioteca

GET /ai/skills

Escopo agents:read

Query customer_id. Skills do Cliente: id, name, description, active, revision, version_id.

POST /ai/skills

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "name": "Trocas e devoluções",
  "description": "Explica a política de troca e coleta os dados do pedido.",
  "body": "Confirme o número do pedido e a data da compra.\nTrocas valem por 30 dias.\nSe o produto tiver defeito, abra um caso para a equipe.",
  "matcher": {
    "any_keywords": [
      "troca",
      "devolução",
      "devolver"
    ],
    "probe_keywords": [
      "defeito",
      "quebrado"
    ]
  }
}

Responde 201 com a skill e affected_agents: [] (uma skill nova ainda não está em nenhum agente).

GET /ai/skills/{id}

Escopo agents:read

Query customer_id. skill, versions e usages (versões de agente que a usam).

PATCH /ai/skills/{id}

Escopo agents:write

Mesmo corpo da criação mais expected_revision. Substitui nome, descrição, instruções e gatilhos. Só cria uma versão nova (que mantém os arquivos do pacote anterior) quando body ou matcher mudam; nome, descrição e active atualizam a skill e avançam revision sem nova versão. Sem active, a skill continua ativa ou desativada como estava; envie active: true ou active: false para mudar.

A resposta traz affected_agents: os agentes em operação que passam a usar a nova versão de conteúdo, cada um com {agent_id, name, version_number} (a versão publicada do agente). Lista vazia quando a alteração não cria versão ou nenhum agente em operação usa a skill. Não há confirmação pela API: confira usages em GET /ai/skills/{id} antes de salvar, se precisar.

{
  "id": "abababab-abab-4bab-8bab-abababababab",
  "name": "Objeções de preço",
  "description": "Quando o contato achar caro.",
  "active": true,
  "revision": "4",
  "version_id": "cdcdcdcd-cdcd-4dcd-8dcd-cdcdcdcdcdcd",
  "affected_agents": [
    {
      "agent_id": "efefefef-efef-4fef-8fef-efefefefefef",
      "name": "Atendimento",
      "version_number": 3
    }
  ]
}

DELETE /ai/skills/{id}

Escopo agents:write

Corpo {customer_id, expected_revision}. Responde 204. Skill usada por versão publicada retorna 409 in_use.

GET /ai/skills/{id}/versions

Escopo agents:read

Query customer_id. Cada versão com body, matcher, manifest (arquivos do pacote: path, size, sha256, kind) e affected_agents: quem estava em operação usando a skill quando a versão foi salva (null em versões anteriores a esse registro).

GET /ai/skills/{id}/references

Escopo agents:read

Query customer_id, version_id e path (começando por references/). Retorna {content} do arquivo de referência daquela versão.

Pacote ZIP

Um pacote tem SKILL.md na raiz e, opcionalmente, references/ (.md, .txt, .csv, .json, .yaml, .yml) e assets/ (.png, .jpg, .jpeg, .webp, .gif, .pdf, .mp3, .ogg, .mp4). Limites: ZIP de até 5 MiB, até 64 arquivos, 1 MiB por arquivo e 5 MiB descompactados. Caminhos absolutos, .., links simbólicos, ZIP64 e arquivos cifrados são recusados. O SKILL.md começa com o cabeçalho:

---
name: Trocas e devoluções
description: Explica a política de troca e coleta os dados do pedido.
matcher:
  any_keywords: [troca, devolução, devolver]
  probe_keywords: [defeito, quebrado]
---
Confirme o número do pedido e a data da compra.
Consulte references/politica.md antes de responder sobre prazos.

Envie o pacote pelo upload direto com kind: "skill". Para criar uma versão de uma skill existente, informe skill_id e expected_revision.

POST /ai/skills/import

Escopo agents:write

Alternativa multipart (customer_id, file, e id com expected_revision para nova versão) para pacotes pequenos. Responde 201 com a skill e affected_agents, como no PATCH.

Catálogo da plataforma

GET /ai/skills/catalog

Escopo agents:read

Query customer_id. Skills publicadas pelo BotoZap, com a versão atual (version_id) e se já foram instaladas no Cliente.

POST /ai/skills/catalog/{slug}/install

Escopo agents:write

Corpo {customer_id, version_id}. Copia aquela versão para a biblioteca do Cliente. Responde 201 com a skill criada, que você pode editar e referenciar em skill_ids.

GET /ai/skills/composition

Escopo agents:read

Query customer_id. Com platform_skills: "all" na versão, o agente também usa as skills da plataforma. Esta rota mostra cada uma com state: available (entra no contexto), overridden_by_copy (o Cliente instalou uma cópia) ou overridden_by_name (o Cliente tem uma skill com o mesmo nome, que prevalece).

Quase acertos

GET /ai/skills/near-misses

Escopo agents:read

Query customer_id, status (pending, accepted, ignored) e skill_id opcionais. Até 50 itens, dos mais recentes: probe, excerpt, occurrences, skill_revision, revision.

POST /ai/skills/near-misses/{id}

Escopo agents:write · chave criada por um Administrador

Aceitar: {customer_id, expected_revision, decision: "accept", phrase, skill_revision}. A frase (1–120) entra em any_keywords numa nova versão da skill; skill_revision é a revisão atual da skill. Ignorar: {customer_id, expected_revision, decision: "ignore"}. Retorna {near_miss, skill}.

Visão geral do Agente de IA · Próxima: Roteadores