multica-creating-agents

Criação de agentes do Multica

Este é o contrato para o caminho de criação de agentes do Multica: o que os pontos de entrada de criação aceitam, o que o servidor valida e rejeita, como cada campo é persistido e quais campos o daemon realmente lê no momento da reivindicação. Não se trata de um manual de parâmetros — ele apresenta fatos rastreados até o código-fonte, e cada reivindicação é respaldada por “arquivo:linha” no arquivo references/creating-agents-source-map.md.

Introdução rápida (inspeção somente leitura)

Esses comandos leem o estado e não têm efeitos colaterais:

multica agent get  --output json      # registro completo do agente persistido
multica agent skills list  --output json   # ligações de habilidades atuais
multica agent env get  --output json  # ambiente em texto simples (somente proprietário/administrador; agentes não têm acesso)

O comando `agent get` retorna o agente armazenado, incluindo `runtime_id`, `model`, `thinking_level`, `service_tier`, `custom_args`, `has_custom_env`, `custom_env_key_count` e `skills`. Ele nunca retorna o `custom_env` em texto simples.

Modelo principal

Um agente é uma linha no escopo do espaço de trabalho (tabela agent). A criação é feita por meio de uma única chamadaPOST /api/agents (multica agent create). No momento da reivindicação da tarefa, o daemon releia a linha do agente e monta a carga útil de tempo de execução — portanto, os campos persistidos, e não a saída no momento da criação, são aqueles com base nos quais o agente é executado.

Dois campos de texto distintos, frequentemente confundidos:

• description é um resumo do catálogo. É armazenado e exibido em listagens; o daemon NÃO o insere no prompt de tempo de execução do agente. Trate-o apenas como metadados voltados para o usuário. Limitado a 255 pontos de código Unicode.
• instruções é o contrato de comportamento em tempo de execução. O daemon as lê no momento da solicitação e as envia ao provedor como as instruções permanentes do agente. Persona, responsabilidades, limites, saída e regras de escalonamento vão aqui, não na descrição.

Pontos de entrada da CLI/API

Chamada mínima de criação (--name e --runtime-id são ambos obrigatórios):

multica agent create --name  --runtime-id  \
  --description "" \
  --instructions "" \
  --output json

O comando `runAgentCreate` cria um corpo JSON e o envia para /api/agents. Ele só adiciona uma chave quando a respectiva opção é fornecida — `description `/`instructions ` com um valor não vazio; o restante (runtime-config, custom-args, model, thinking-level, service-tier, visibility, …) no caso de alteração do parâmetro — portanto, parâmetros omitidos assumem os padrões do servidor, em vez de enviar strings vazias.

O corpo HTTP (CreateAgentRequest) aceita: name, description, instructions, avatar_url, runtime_id, runtime_config, custom_env, custom_args, model, thinking_level, service_tier, visibility, max_concurrent_tasks, mcp_config.

Contratos de campos

Padrões quando omitidos: runtime_config → {}, custom_env → {}, custom_args → [], avatar_url → um emoji aleatório :, visibilidade → privada, max_concurrent_tasks → 6 (todos materializados no lado do servidor antes da inserção).custom_args/runtime_config são do tipo []string/any e marshalados como estão — a rejeição do formato JSON ocorre na CLI, não no manipulador de criação.

thinking_level é validado apenas no nível do provedor: provedores de catálogo fixo rejeitam um literal não reconhecido, enquanto provedores de catálogo dinâmico, como Codex/OpenCode, aceitam um token sintaticamente seguro. Um valor não suportado pelo modelo escolhido NÃO é rejeitado aqui — o daemon verifica seu catálogo de modelos local no momento da execução, registra um aviso e omite a substituição incompatível.

Defina-o na CLI com --thinking-level ao criar e atualizar o agente, espelhando --model: o sinalizador é um simples repasse para o campo thinking_level de nível superior e, na atualização, uma string vazia (--thinking-level "") o redefine para o padrão de tempo de execução. A CLI deliberadamente não enumera os níveis válidos — eles são específicos do tempo de execução/modelo (o Claude atualmente usa low|medium|high|xhigh|max; os valores do Codex são descobertos a partir do catálogo de modelos do tempo de execução). Ela encaminha o token, o servidor aplica o filtro de enumeração fixa ou token seguro do provedor, e o daemon realiza a verificação exata de modelo/nível. Um tempo de execução cujo provedor não possua o conceito de “thinking” rejeita qualquer valor não vazio com um código de erro 400.

service_tier é o controle de velocidade do Codex de primeira classe correspondente. Defina-o com --service-tier na criação/atualização; use --service-tier "" na atualização para limpá-lo. O catálogo de modelos do ambiente de execução possui tanto a disponibilidade quanto a cópia de exibição (atualmente prioridade, mostrada como Rápido). O servidor aceita IDs de catálogo do Codex futuras e seguras, enquanto o daemon verifica o par exato de modelo/nível antes da execução e omite uma substituição obsoleta e incompatível. Agentes sem um modelo explícito falham com status “fechado” porque o modelo efetivo do config.toml é desconhecido.

modelo vs custom_args

O `model` é uma coluna persistida de primeira classe que o daemon lê diretamente. custom_args são argumentos brutos da CLI do provedor. A ajuda da CLI observa que alguns provedores (codex app-server, openclaw) rejeitam --model dentro de custom_args — mas essa é uma orientação documentada da CLI, não uma invariável imposta pelo servidor; nada no manipulador de criação verifica se há um sinalizador de modelo em custom_args.

Ambiente e segredos

custom_env contém informações confidenciais. A CLI oferece três canais de entrada; dois mantêm os segredos fora do histórico do shell e da lista de processos:

multica agent create --name  --runtime-id  --custom-env-stdin --output json
multica agent create --name  --runtime-id  --custom-env-file <0600-json> --output json

--custom-env-stdin lê o objeto JSON da entrada padrão (stdin); --custom-env-file o lê de um arquivo (modo sugerido 0600). O terceiro canal, --custom-env , coloca o valor na linha de comando, onde o histórico do shell e o comando `ps` podem visualizá-lo — evite usá-lo para segredos reais.

Fatos do lado da leitura (estas são as suposições erradas a serem evitadas):

• Os recursos do agente nunca expõem o `custom_env` em texto simples. Os comandos `list/get/create/update` do agente e os eventos do WS retornam apenas `has_custom_env ` (bool) e `custom_env_key_count ` (int).
• A leitura de valores em texto simples requer o endpoint GETdedicado /api/agents/{id}/env (multica agent env get). O acesso é restrito aos membros proprietários/administradores do espaço de trabalho, e os agentes são impedidos de acessar, independentemente da função do membro responsável — um agente em execução não pode ler os segredos de outro agente.
• A gravação de valores após a criação NÃO passa pela atualização do agente. O manipulador genérico de atualização rejeita qualquer campo `custom_env` com um código 400 (“use PUT /api/agents/{id}/env”). As gravações de ambiente em texto simples são tratadas pelo PUT /api/agents/{id}/env (multica agent env set), que é restrito apenas ao proprietário/administrador e grava uma linha de auditoria.

mcp_config

mcp_config é a configuração do servidor MCP do agente (um objeto JSON como {"mcpServers": {…}}). Também se trata de informação confidencial — as entradas MCP costumam incorporar tokens de API — e oferece os mesmos três canais de entrada que custom_env, tanto na criação quanto na atualização do agente:

multica agent create --name  --runtime-id  --mcp-config-file <0600-json> --output json
multica agent update  --mcp-config-stdin --output json
multica agent update  --mcp-config 'null'   # limpa a configuração

--mcp-config-stdin / --mcp-config-file mantêm o valor fora do histórico do shell e do ps; a opção inline --mcp-config não faz isso. A CLI exige umobjeto JSON ou o valor literal null; um array de nível superior ou um tipo primitivo é rejeitado no lado do cliente, e entradas vazias de stdin/arquivo geram erros em vez de serem limpas silenciosamente.

Duas diferenças entre o mcp_config e o custom_env:

• Ele PODE ser configurado por meio da atualização do agente. Ao contrário do custom_env, o mcp_config não possui um endpoint auditado dedicado — o PUT genérico /api/agents/{id} o aceita. Três estados de acordo com o corpo bruto da solicitação: campo omitido → nenhuma alteração; null → limpar; objeto → substituir.
• Ele é serializado na leitura, mas redigido.As chamadas get/list do agente retornam mcp_config apenas para chamadores autorizados a visualizar segredos do agente; caso contrário, o campo é nulo e mcp_config_redacted é verdadeiro. Os atores do agente nunca o veem, e um espaço de trabalho pode forçar a redação para todos.

O suporte dos provedores não é uniforme: o Qwen Code aceita um mcp_config gerenciado por meio de um arquivo JSON temporário 0600 de propriedade do daemon, passado com --mcp-config; ele é removido quando a execução é encerrada. Deixe o campo não definido (nulo) para herdar as configurações nativas do Qwen Code.

Vinculação de habilidades

A criação de um agente NÃO vincula nenhuma habilidade do espaço de trabalho — o vinculamento é uma chamada separada após a criação do agente. Dois verbos distintos:

• add é aditivo — ele mescla os IDs fornecidos com as ligações existentes (POST /api/agents/{id}/skills/add).
• set substitui tudo — ele sobrescreve toda a lista de vinculações exatamente pelos IDs fornecidos (PUT /api/agents/{id}/skills); --skill-ids '' limpa tudo.

multica agent skills add  --skill-ids  --output json
multica agent skills list  --output json

No momento da solicitação, o daemon monta as habilidades do agente como habilidades vinculadas ao espaço de trabalho PRIMEIRO e, em seguida, acrescenta as habilidades integradas à plataforma. O `LoadAgentSkills` carrega o conteúdo de cada habilidade vinculada, além de seus arquivos de suporte; as habilidades integradas são incorporadas no momento da compilação e carregadas a partir do `SKILL.md` e dos arquivos associados. Ambos chegam ao provedor como conteúdo de habilidade — e é por isso que a capacidade pertence a uma habilidade vinculada, e não deve ser inserida nas instruções.

Efeitos colaterais que requerem aprovação

Somente leitura (seguro): obtenção do agente, lista de habilidades do agente, obtenção do ambiente do agente.

Alteração de estado (requer uma instrução explícita — não execute especulativamente):

• criação de agente multica — insere uma nova linha de agente.
• multica agent skills add / set — altera as ligações (set é destrutivo: ele descarta as ligações que não constam na nova lista).
• multica agent env set — sobrescreve todo o mapa custom_env e grava uma linha de auditoria.

Suposições errôneas comuns

• “A descrição é o prompt.” Não é — apenas as instruções chegam ao tempo de execução. Uma descrição detalhada com instruções vazias gera um shell nomeado sem contrato operacional.
• “Create vincula as habilidades do agente.” Não vincula; vincule explicitamente posteriormente.
• “O `agent update` pode alternar o ambiente.” Não pode — retorna um erro 400 no `custom_env`; use o ponto de extremidade do ambiente.
• “O mcp_config se comporta como o custom_env na atualização.” Não se comporta — o mcp_config PODE ser configurado via `agent update ` (--mcp-config), com --mcp-config nulo para limpar; apenas o custom_env é controlado pelo endpoint de ambiente dedicado.
• “O get do agente mostra os valores do env.” Ele mostra apenas has_custom_env e custom_env_key_count.
• “Uma combinação inválidade thinking_level/model é detectada na criação.” Apenas um literal desconhecido no nível do provedor é — lacunas específicas do modelo falham em tempo de execução.
• “set e add são intercambiáveis para habilidades.” set substitui todas as vinculações; usá-lo quando você pretendia usar add remove silenciosamente as capacidades.

Referências

references/creating-agents-source-map.md mapeia cada contrato acima para seu arquivo:linha na árvore atual, o efeito em tempo de execução e um comando de verificação seguro, somente leitura .