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

Crie uma linha de base de modelo do Forward para sessões futuras.

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 opcional para requisições que alteram estado.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do modelo. Deve ter entre 1 e 256 caracteres e ser único na conta.
`model`	string	Sim	Identificador do modelo, como `ultimate`.
`environment_id`	string	Sim	Ambiente padrão aplicado às sessões criadas a partir deste modelo.
`description`	string	Não	Descrição do modelo. Até 2.048 caracteres.
`system`	string	Não	Prompt do sistema. Até 100.000 caracteres.
`tools`	array	Não	Configurações de ferramentas. Até 128 itens.
`mcp_servers`	array	Não	Configurações de servidores MCP. Até 20 itens.
`skills`	array	Não	Vinculações de habilidades. Até 20 itens.
`multiagent`	object	Não	Configuração de Managed Agents.
`vault_ids`	array	Não	IDs de vault padrão aplicados às sessões.
`files`	object	Não	Recursos de arquivo padrão, indexados por ID de arquivo.
`environment_variables`	object	string	Não	Variáveis de ambiente padrão para as sessões.
`metadata`	object	Não	Metadados personalizados.

Objetos de configuração aninhados

Arquivos

files é um mapa indexado por ID de arquivo. Não inclua file_id, id ou resource_id em cada entrada. O Forward injeta o mount_path automaticamente ao iniciar uma sessão.

Campo	Tipo	Obrigatório	Descrição
`enabled`	boolean	Não	A omissão do campo equivale a `true`. Em uma Identity Config, defina como `false` para desativar um arquivo herdado.

Itens de tools[]

Cada entrada em tools seleciona uma estrutura com base no type.

Campo	Tipo	Aplica-se a	Descrição
`type`	string	Todos	Obrigatório. Um entre `agent_toolset_20260401`, `mcp_toolset` ou `custom`.
`enabled_tools`	array	`agent_toolset_20260401`	Lista de permissões simplificada. Um array não vazio ativa apenas as ferramentas integradas listadas.
`disallowed_tools`	array	`agent_toolset_20260401`	Lista de bloqueios simplificada. Compilada nas configurações de ferramentas desativadas.
`configs`	array	`agent_toolset_20260401`, `mcp_toolset`	Estado de ativação e política de permissão por ferramenta.
`mcp_server_name`	string	`mcp_toolset`	Obrigatório. Deve corresponder a um dos valores de `mcp_servers[].name`.
`name`	string	`custom`	Obrigatório. Nome da ferramenta personalizada; não deve entrar em conflito com o nome de uma ferramenta integrada.
`description`	string	`custom`	Obrigatório. Descrição legível da ferramenta personalizada.
`input_schema`	object	`custom`	JSON Schema obrigatório. `input_schema.type` deve ser `object`.

Os nomes das ferramentas integradas incluem Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch e DeliverArtifacts.

Configuração de ferramenta

Cada entrada em tools[].configs utiliza a seguinte estrutura.

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da ferramenta. Use o nome da ferramenta integrada para um conjunto de ferramentas integrado ou o nome da ferramenta MCP para um conjunto de ferramentas MCP.
`enabled`	boolean	Não	`false` oculta e nega a ferramenta; `true` a ativa explicitamente.
`permission_policy`	object	Não	Comportamento de permissão em tempo de execução.

Política de permissão

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Um entre `always_allow`, `always_ask` ou `always_deny`.

Servidores MCP

Campo	Tipo	Obrigatório	Descrição
`type`	string	Não	Atualmente, apenas `http` tem suporte. Quando omitido, a configuração efetiva trata a entrada como um servidor MCP HTTP.
`name`	string	Sim	Nome do servidor MCP, único no modelo. Referenciado por `tools[].mcp_server_name`.
`url`	string	Sim	URL do endpoint MCP HTTP com suporte a streaming.

Itens de skills[]

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Pode ser `custom` ou `qoder`.
`skill_id`	string	Sim	ID da habilidade.
`version`	string	Não	Versão da habilidade. Se omitida, assume a versão mais recente.
`enabled`	boolean	Não	A omissão do campo equivale a `true`. Defina como `false` para excluir a habilidade da configuração compilada do agente.

Exemplo de requisição

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/templates' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support assistant",
    "description": "Handles pre-sales and after-sales support",
    "model": "ultimate",
    "system": "You are a helpful support assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "configs": [
          { "name": "Read", "enabled": true },
          { "name": "Grep", "enabled": true },
          { "name": "WebSearch", "enabled": true }
        ]
      }
    ],
    "mcp_servers": [],
    "skills": [
      {
        "type": "custom",
        "skill_id": "skill_customer_reply",
        "version": "1",
        "enabled": true
      }
    ],
    "environment_id": "env_support",
    "vault_ids": ["vault_crm"],
    "files": {
      "file_019eXXXX": { "enabled": true }
    },
    "environment_variables": {
      "BASE_MODE": "support"
    },
    "metadata": {}
  }'

Exemplo de resposta

HTTP 201 Created

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant",
  "description": "Handles pre-sales and after-sales support",
  "status": "active",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        { "name": "Read", "enabled": true },
        { "name": "Grep", "enabled": true },
        { "name": "WebSearch", "enabled": true }
      ]
    }
  ],
  "mcp_servers": [],
  "skills": [
    {
      "type": "custom",
      "skill_id": "skill_customer_reply",
      "version": "1",
      "enabled": true
    }
  ],
  "multiagent": null,
  "environment_id": "env_support",
  "vault_ids": ["vault_crm"],
  "files": {
    "file_019eXXXX": { "enabled": true }
  },
  "environment_variables": {
    "BASE_MODE": "support"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

Campos da resposta

Campo	Tipo	Descrição
`type`	string	Sempre `template`.
`id`	string	ID do modelo.
`status`	string	`active` ou `archived`.
`environment_id`	string	ID do ambiente padrão aplicado às sessões.
`vault_ids`	array	IDs de vault padrão.
`files`	object	Configuração de recursos de arquivo padrão, indexada por ID de arquivo.
`created_at`	string	Timestamp de criação.
`updated_at`	string	Timestamp da última atualização.

Erros

HTTP	Tipo	Gatilho
400	`invalid_request_error`	Corpo da requisição ou valor de campo inválido.
401	`authentication_error`	PAT inválido ou expirado.
404	`not_found_error`	Ambiente, habilidade, vault ou arquivo referenciado inexistente.
409	`conflict_error`	Já existe um modelo com o mesmo nome.

Observações

Não envie um ID de modelo na requisição de criação. O Forward gera o id automaticamente.
files é indexado por ID de arquivo. Não inclua file_id, id ou resource_id em cada entrada.
O Forward injeta os caminhos de montagem de arquivos automaticamente ao iniciar uma sessão.