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

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 criações duplicadas.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do agente (1 a 256 caracteres).
`model`	string\	object	Sim	Identificador do modelo. Aceita uma string, como `"ultimate"`, ou um objeto.
`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. Consulte a estrutura do elemento `tools` abaixo.
`mcp_servers`	array	Não	Lista de configurações de servidores MCP no formato `[{"name":"[name]","type":"http","url":"[mcp_server_url]"}]`. Configure a autenticação pelo Vault.
`skills`	array	Não	Vinculações 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.

Estrutura do elemento `tools`

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

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Identificador do tipo de conjunto de ferramentas.
`enabled_tools`	array	Não	Lista de permissões de ferramentas atômicas a ativar. A omissão do campo ou o envio de um array vazio `[]` ativa todas as ferramentas integradas. Um array não vazio atua como lista de permissões restrita; ferramentas fora dela permanecem invisíveis ao modelo.

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",
    "instructions": "You are a documentation test 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/sse"
      }
    ]
  }'

Exemplo de resposta

HTTP 201 Created

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "You are a documentation test assistant.",
  "instructions": "You are a documentation test 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/sse"
    }
  ],
  "default_environment": "",
  "version": 1,
  "archived": false,
  "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	Sempre `"agent"`.
`id`	string	Identificador exclusivo do agente com prefixo `"agent_"`.
`name`	string	Nome do agente.
`description`	string	Descrição do agente.
`model`	string	Identificador do modelo.
`instructions`	string	Prompt do sistema.
`system`	string	Alias de `instructions` (obsoleto; use `instructions`).
`tools`	array	Lista de configurações de ferramentas.
`mcp_servers`	array	Configuração de servidores MCP.
`default_environment`	string	Ambiente de execução padrão.
`version`	integer	Número da versão atual (inicia em 1).
`archived`	boolean	Indica se o agente está arquivado.
`archived_at`	string \	null	Data e hora de arquivamento (ISO 8601). Retorna `null` se não estiver arquivado.
`created_at`	string	Data e hora de criação (ISO 8601).
`updated_at`	string	Data e hora da última atualização (ISO 8601).

Erros

HTTP	Tipo	Gatilho
400	`invalid_request_error`	Campo obrigatório `name` ausente.
400	`invalid_request_error`	O campo `name` excede 256 caracteres.
400	`invalid_request_error`	Campo obrigatório `model` ausente.
400	`invalid_request_error`	Configuração malformada em `mcp_servers` ou `skills`.
400	`invalid_request_error`	O campo `skills` ultrapassa o limite de 20 entradas.
401	`authentication_error`	PAT inválido ou expirado.
403	`permission_error`	Chamador não autorizado para esta operação.

Exemplo de resposta de erro:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

Para ver o envelope completo de erros, consulte Erros.

Cabeçalhos da requisição

Corpo da requisição

Estrutura do elemento tools

Exemplo de requisição

Exemplo de resposta

Campos da resposta

Erros

Estrutura do elemento `tools`