Qoder CN Series:Definir um Agent

Conceitos principais

Considere o Agent como uma "descrição de cargo":

O Agent não executa tarefas diretamente; ele é apenas uma configuração. Uma sessão vinculada a esse Agent realiza a execução das tarefas.

Referência de parâmetros

Modelo

O campo model especifica o modelo que o Agent utiliza.

Ferramentas

O campo tools é um array de objetos de ferramenta. Atualmente, há suporte apenas ao conjunto de ferramentas agent_toolset_20260401. Para ativar ferramentas atômicas nesse conjunto, liste-as no array enabled_tools:

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

Valores disponíveis para enabled_tools (os valores diferenciam maiúsculas de minúsculas e devem estar em PascalCase):

Para obter mais configurações de ferramentas, consulte Configuração de ferramentas do Agent.

Gerencie agents

Para todas as operações CRUD, consulte Referência da API / Agents. Os exemplos a seguir abordam fluxos de trabalho comuns.

Crie

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "You are a code review expert. Review the code line by line and output issues and improvement suggestions in Markdown.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .

Uma solicitação bem-sucedida retorna 201 Created. A version começa em 1.

Consultar

# Get a single Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

# List Agents with pagination
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

Atualize

Ao atualizar um Agent, você deve fornecer a version atual. Para mais informações, consulte a seção Gerenciamento de versões abaixo.

curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "You are a senior code review expert, focusing on security vulnerabilities and performance issues.",
    "version": 1
  }' | jq .

Uma solicitação bem-sucedida retorna 200 OK, e a version incrementa em 1.

Exclua

curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

Excluir um Agent não encerra as sessões ativas vinculadas a ele. Uma sessão captura um snapshot da configuração do Agent no momento da criação.

Gerenciamento de versões

A API do Agent usa controle de concorrência otimista (OCC):

• A version começa em 1 após a criação.

• Após cada atualização bem-sucedida, a version incrementa automaticamente em 1.

• As solicitações de atualização devem incluir a version atual. Existem dois cenários de falha:

  • Campo version ausente — retorna 400 invalid_request_error ("Field 'version' is required.")

  • A version foi fornecida, mas não corresponde à versão no servidor — retorna 409 conflict_error

Esse mecanismo impede que modificações simultâneas se sobrescrevam.

Como lidar com conflitos 409

Se a solicitação falhar porque a versão está desatualizada, você receberá este erro:

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}

Para resolver o conflito:

1. Faça uma requisição GET do Agent mais recente para obter a version atual.

2. Reaplique as alterações desejadas aos dados mais recentes do objeto.

3. Use a nova version para fazer outra requisição PUT.

Melhores práticas

1. Convenções de nomenclatura — Adote o formato team-purpose, como backend-code-review ou frontend-test-gen.

2. Refinamento de prompts — Especifique a função, o formato de saída e as restrições no campo system.

3. Princípio do menor privilégio: Conceda apenas as tools essenciais para a tarefa e minimize riscos.

4. Uso eficaz de metadados: Adicione pares chave-valor para categorizar os Agents e facilitar a filtragem e a auditoria.

5. Bloqueio de versão em produção — Ao criar uma sessão, use o formato {"id": ..., "version": ...} para fixar a versão do Agent. Isso evita que novas versões afetem seus serviços online.

Perguntas frequentes

P: Atualizar um Agent afeta as sessões em execução? Não. Uma sessão fica vinculada a uma versão específica do Agent no momento da criação. P: O array tools** pode estar vazio? Sim. Um Agent sem tools só mantém conversas baseadas em texto e não executa ações. P: Existe limite de comprimento para o campo name**? Mantenha-o abaixo de 64 caracteres, com letras minúsculas, números e hifens. P: Como reverter para uma versão anterior de um Agent? Não há suporte para reversão automática. Salve a configuração do Agent antes de atualizá-la. Para reverter, faça uma requisição PUT com a configuração antiga e use o número da version mais recente.

Próximos passos

• Ambiente Cloud — Configure a infraestrutura onde o Agent será executado.

• Iniciar uma sessão — Crie uma sessão com um Agent.

• Configuração de ferramentas do Agent — Saiba mais sobre tipos de ferramentas e políticas de permissão.