Criar um agente - : Central de Documentação do Alibaba Cloud

Crie uma nova configuração de agente.

Importante

O novo site de documentação do Qoder CN já está disponível. O conteúdo deste site pode não refletir os recursos e as alterações mais recentes do product. Acesse docs.qoder.cn para consultar a documentação mais recente do product.

POST /api/v1/cloud/agents

Crie uma nova configuração de agente.

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <PAT>`
`Content-Type`	Sim	`application/json`
`Idempotency-Key`	Não	Chave de idempotência para evitar a criação duplicada

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do agente, de 1 a 256 caracteres
`model`	string	object	Sim	Identificador do modelo. Passe uma string (por exemplo, `"ultimate"`) ou um objeto de modelo de agente para também configurar `effort` ou `context_window`. Para consultar os valores disponíveis, use a API List models
`system`	string	Não	Prompt do sistema, com até 100.000 caracteres
`description`	string	Não	Descrição do agente, com até 2.048 caracteres
`tools`	Agent tool array	Não	Lista de configurações de ferramentas, com até 128 itens
`mcp_servers`	MCP server array	Não	Lista de configurações de servidores MCP, com até 20 itens. Configure a autenticação por meio do Vault
`skills`	Skill binding array	Não	Lista de vinculações de habilidades, com até 20 itens
`metadata`	Metadata object	Não	Metadados personalizados. O padrão é `{}` quando omitido
`multiagent`	Multiagent	Não	Configuração de multiagente. Ao definir esta opção, configure também a ferramenta `agent_toolset_20260401`

Exemplo de requisição

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent",
    "model": "ultimate",
    "system": "You are a documentation testing assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "weather-service",
        "url": "https://mcp.example.com/mcp"
      }
    ]
  }'

Para configurar o esforço de raciocínio ou a janela de contexto, passe model como um objeto:

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-tuned",
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 400000
    },
    "system": "You are a documentation testing assistant"
  }'

Exemplo de resposta

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "You are a documentation testing assistant",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "weather-service",
      "url": "https://mcp.example.com/mcp"
    }
  ],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 1,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:26:39.61669Z"
}

Campos da resposta

Campo	Tipo	Descrição
`type`	string	Valor fixo `"agent"`
`id`	string	Identificador exclusivo do agente, com o prefixo `"agent_"`
`name`	string	Nome do agente
`description`	string	Descrição do agente
`model`	string	object	Identificador do modelo. Consulte Agent model para obter detalhes
`system`	string	Prompt do sistema
`tools`	Agent tool array	Lista de configurações de ferramentas
`mcp_servers`	MCP server array	Configuração de servidores MCP
`skills`	Skill binding array	Lista de vinculações de habilidades
`metadata`	Metadata object	Metadados personalizados
`multiagent`	Multiagent	null	Configuração de multiagente. `null` quando não definido
`version`	integer	Número da versão atual. Começa em 1 e incrementa a cada alteração
`archived_at`	string	null	Carimbo de data e hora de arquivamento (ISO 8601). `null` quando não arquivado
`created_at`	string	Carimbo de data e hora de criação (ISO 8601)
`updated_at`	string	Carimbo de data e hora da última atualização (ISO 8601)

Erros

HTTP	Tipo	Condição
400	`invalid_request_error`	O campo obrigatório `name` está ausente
400	`invalid_request_error`	`name` não é uma string; a mensagem de erro é `Field 'name' must be a string.`
400	`invalid_request_error`	`name` excede 256 caracteres
400	`invalid_request_error`	O campo obrigatório `model` está ausente
400	`invalid_request_error`	`model.effort` não é um dos valores: `none`, `low`, `medium`, `high`, `xhigh`, `max`
400	`invalid_request_error`	`model.context_window` não é um número inteiro positivo
400	`invalid_request_error`	`model.speed` foi fornecido; use `model.effort` em seu lugar
400	`invalid_request_error`	`tools` excede o limite de 128 itens
400	`invalid_request_error`	O formato de configuração de `mcp_servers` ou `skills` é inválido
400	`invalid_request_error`	`skills` excede o limite de 20 itens
400	`invalid_request_error`	`multiagent.type` não é `"coordinator"`
400	`invalid_request_error`	`multiagent.agents` está vazio ou excede o limite de 20 itens
400	`invalid_request_error`	`multiagent` está definido, mas `tools` não contém `agent_toolset_20260401`
400	`invalid_request_error`	Um ID de agente referenciado em `multiagent.agents` não existe
401	`authentication_error`	O PAT é inválido ou expirou
403	`permission_error`	Permissões insuficientes para esta operação

Exemplo de resposta de erro:

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

Para a especificação completa do envelope de erros, consulte Errors.