Atualizar um agente - Qoder CN Series: Central de Documentação do Alibaba Cloud

Atualize a configuração de um agente existente. Este recurso usa controle de concorrência otimista (OCC); portanto, forneça o valor atual de version no corpo da requisição.

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <PAT>`
`Content-Type`	Sim	`application/json`

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`agent_id`	string	Sim	Identificador exclusivo do agente.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`version`	integer	Sim	Número da versão atual para OCC. Deve corresponder ao valor no servidor.
`name`	string	Não	Nome do agente (1 a 256 caracteres).
`model`	string\	object	Não	Identificador do modelo.
`instructions`	string	Não	Prompt do sistema.
`description`	string	Não	Descrição do agente.
`tools`	array	Não	Lista de configurações de ferramentas.
`mcp_servers`	array	Não	Lista de configurações de servidores MCP.
`skills`	array	Não	Vínculos de habilidades no formato `[{"type":"custom","skill_id":"[skill_id]"}]`. Máximo de 20 entradas.
`metadata`	object	Não	Pares chave-valor de metadados personalizados.
`default_environment`	string	Não	Ambiente de execução padrão.

Exemplo de requisição

curl -X PUT "https://api.qoder.com.cn/api/v1/cloud/agents/agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-updated",
    "model": "ultimate",
    "instructions": "You are the updated documentation test assistant.",
    "description": "Used for API documentation testing.",
    "version": 1
  }'

Exemplo de resposta

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "Used for API documentation testing.",
  "model": "ultimate",
  "system": "You are the updated documentation test assistant.",
  "instructions": "You are the updated documentation test assistant.",
  "tools": [],
  "mcp_servers": [],
  "default_environment": "",
  "version": 2,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

Controle de concorrência otimista (OCC)

As requisições de atualização usam o número da versão para implementar o bloqueio otimista:

O cliente chama o método GET para obter a version atual do agente.
O cliente envia a atualização com essa version no corpo da requisição.
O servidor verifica se a version informada corresponde ao valor atual no servidor.
Se houver correspondência, a atualização é concluída e a version é incrementada em 1.
Caso contrário, o servidor retorna o erro 409 Conflict.

Esse mecanismo impede que clientes concorrentes sobrescrevam alterações uns dos outros no mesmo agente.

Erros

HTTP	Tipo	Gatilho
400	`invalid_request_error`	Corpo da requisição ou valor de campo inválido.
400	`invalid_request_error`	O campo `skills` excede o máximo de 20 entradas.
401	`authentication_error`	PAT inválido ou expirado.
403	`permission_error`	Chamador não autorizado a atualizar este agente.
404	`not_found_error`	Nenhum agente encontrado com o ID especificado.
409	`conflict_error`	A `version` não corresponde: modificação concorrente detectada.

Exemplo de resposta para conflito de versão (409):

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

Para visualizar a estrutura completa de erros, consulte Erros.

Observações

O campo version é obrigatório; omiti-lo causa falha na atualização.
A version é incrementada após cada atualização bem-sucedida.
A operação segue semântica de atualização parcial (merge): campos opcionais ausentes no corpo da requisição mantêm os valores anteriores; apenas os campos fornecidos explicitamente são atualizados.
Use a API Listar versões do Agente para visualizar o histórico de versões.