:Agent Tools

O que as ferramentas fazem

Ao executar uma tarefa, o Agent determina quais capacidades pode acionar com base na configuração de tools. Todas as ferramentas são configuradas por meio de um único objeto { "type": "agent_toolset_20260401", "enabled_tools": [...] }, habilitando seletivamente ferramentas atômicas no array enabled_tools.

Quando enabled_tools é uma lista de permissões não vazia, as ferramentas fora dela ficam invisíveis para o modelo e nenhuma tentativa de invocação é realizada. Quando enabled_tools é omitido ou recebe um array vazio, todas as ferramentas integradas ficam expostas ao modelo. Quando o próprio campo tools é omitido ou definido como [], o modelo não recebe nenhum schema de ferramenta (consulte o FAQ abaixo).

Ferramentas disponíveis

Observações:

• Os nomes das ferramentas são grafados com inicial maiúscula (Bash, não bash); eles também aparecem em maiúscula nos fluxos de eventos

• Omitir enabled_tools ou passar um array vazio [] habilita todas as ferramentas integradas (incluindo DeliverArtifacts listada acima). Para que o Agent não tenha nenhuma ferramenta, omita o campo tools inteiro ou defina-o como [].

• Cada nome de ferramenta em enabled_tools é validado — informar um nome desconhecido (por exemplo, "Foo") retorna 400: "unknown tool name 'Foo'"

• O schema antigo por objeto de ferramenta (como {"type": "bash_20250124"}) não é mais suportado

Formato atual: objeto único

A configuração de tools é um único objeto que ativa ferramentas específicas por meio do array enabled_tools:

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Defina ao criar um Agent:

curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-agent",
    "model": "ultimate",
    "instructions": "You are a development assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }'

Exemplos de configuração

Mínima (somente CLI)

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash"]
    }
  ]
}

Stack completa de desenvolvimento

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Criar uma nova versão (PUT — substituição completa)

Use PUT para criar uma nova versão do Agent com a configuração de ferramentas atualizada:

curl -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

Inspecionar a configuração atual de ferramentas

curl https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" | jq '.tools'

Exemplo de saída:

[
  {
    "type": "agent_toolset_20260401",
    "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
  }
]

FAQ

P: O que acontece se eu não configure ferramentas? R: O Agent não terá ferramentas disponíveis e só poderá realizar conversas em texto simples. Para atribuir qualquer capacidade de ferramenta ao Agent, passe pelo menos [{"type":"agent_toolset_20260401"}] (o que habilita todas as ferramentas integradas).

P: Posso sobrescrever as ferramentas no nível da Session? R: Não no momento. A configuração de ferramentas está vinculada ao Agent, e todas as Sessions desse Agent compartilham o mesmo conjunto de ferramentas.

P: A ordem das ferramentas importa? R: Não. O Agent decide qual ferramenta acionar com base no contexto da tarefa.

P: O sufixo de versão muda com o tempo? R: Sim. À medida que novas versões de ferramentas são lançadas, novos sufixos com data são introduzidos. Acompanhe o changelog e adote o sufixo mais recente.