Qoder CN Series:Agent Tools

Função das ferramentas

Durante a execução de uma tarefa, o Agent decide quais capacidades chamar com base na configuração de tools. Um único objeto { "type": "agent_toolset_20260401", "enabled_tools": [...] } configura todas as ferramentas e ativa seletivamente as ferramentas atômicas no array enabled_tools.

Se enabled_tools for uma lista de permissões não vazia, o modelo não verá as ferramentas fora da lista nem tentará invocá-las. Se enabled_tools for omitido ou for um array vazio, todas as ferramentas integradas ficarão expostas ao modelo. Caso o campo tools seja omitido ou definido como [], o modelo não receberá nenhum schema de ferramenta (consulte o FAQ abaixo).

Ferramentas disponíveis

Observações:

• Os nomes das ferramentas usam inicial maiúscula (Bash, não bash) e também aparecem assim nos fluxos de eventos.

• Omitir enabled_tools ou passar um array vazio [] ativa todas as ferramentas integradas (incluindo DeliverArtifacts). Para deixar o Agent sem nenhuma ferramenta, omita todo o campo tools ou defina-o como [].

• Cada nome em enabled_tools passa por validação. Nomes desconhecidos (por exemplo, "Foo") retornam 400: "unknown tool name 'Foo'".

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

Formato atual: Objeto único

A configuração de ferramentas usa um único objeto que alterna ferramentas específicas pelo array enabled_tools:

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

Defina ao crie 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 (apenas 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"]
    }
  ]
}

Crie uma nova versão (PUT com substituição completa)

Use PUT para crie 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á manter conversas em texto simples. Para conceder qualquer capacidade de ferramenta ao Agent, passe pelo menos [{"type":"agent_toolset_20260401"}] (isso ativa todas as ferramentas integradas).

P: Posso sobrescrever ferramentas no nível da Session? R: Atualmente não. 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 invocar com base no contexto da tarefa.

P: O sufixo de versão mudará com o tempo? R: Sim. Novas versões de ferramentas introduzem novos sufixos datados. Acompanhe o changelog e adote o sufixo mais recente.