multica-creating-agents

Creación de agentes de Multica

Este es el contrato para la ruta de creación de agentes de Multica: qué aceptan los puntos de entrada de creación, qué valida y rechaza el servidor, cómo se almacena cada campo y qué campos lee realmente el demonio en el momento de la reclamación. No se trata de un manual de parámetros, sino que expone hechos rastreados hasta el código fuente, y cada afirmación está respaldada por la referencia «archivo:línea» en references/creating-agents-source-map.md.

Inicio rápido (inspección de solo lectura)

Estos comandos leen el estado y no tienen efectos secundarios:

multica agent get  --output json      # registro completo del agente almacenado
multica agent skills list  --output json   # enlaces de habilidades actuales
multica agent env get  --output json  # entorno en texto plano (solo propietario/administrador; denegado a los agentes)

La orden «agent get» devuelve el agente guardado, incluyendo runtime_id, model, thinking_level, service_tier, custom_args, has_custom_env, custom_env_key_count y skills. Nunca devuelve custom_env en texto plano.

Modelo básico

Un agente es una fila con ámbito de espacio de trabajo (tabla «agent»). Su creación se realiza mediante una única petición POST a /api/agents (multica agent create). En el momento de la reclamación de la tarea, el daemon vuelve a leer la fila del agente y ensambla la carga útil de tiempo de ejecución; por lo tanto, son los campos persistidos, y no la salida del momento de la creación, los que el agente utiliza para ejecutarse.

Dos campos de texto distintos, que a menudo se confunden:

• «description» es un resumen del catálogo. Se almacena y se muestra en los listados; el daemon NO lo inserta en la indicación de ejecución del agente. Trátalo únicamente como metadatos destinados a los usuarios. Tiene un límite de 255 puntos de código Unicode.
• Las «instrucciones» son el contrato de comportamiento en tiempo de ejecución. El demonio las lee en el momento de la solicitud y las envía al proveedor como las instrucciones permanentes del agente. La identidad, las responsabilidades, los límites, la salida y las reglas de escalación van aquí, no en la «descripción».

Puntos de entrada de la CLI/API

Llamada mínima de creación (se requieren tanto--name como --runtime-id ):

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

runAgentCreate genera un cuerpo JSON y lo envía a /api/agents. Solo añade una clave cuando se ha proporcionado su parámetro correspondiente—descripción/instrucciones con un valor no vacío; el resto (runtime-config, custom-args, model, thinking-level, service-tier, visibility, …) se asigna según el valor de la bandera — de modo que las banderas omitidas se sustituyen por los valores predeterminados del servidor en lugar de enviar cadenas vacías.

El cuerpo HTTP (CreateAgentRequest) acepta: 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

Valores por defecto cuando se omiten: runtime_config → {}, custom_env → {}, custom_args → [], avatar_url → un emoji aleatorio :, visibility → private, max_concurrent_tasks → 6 (todo ello materializado en el lado del servidor antes de la inserción).custom_args/runtime_config tienen el tipo []string/any y se marshalizan tal cual; el rechazo por la estructura JSON se produce en la CLI, no en el controlador de creación.

thinking_level solo se valida a nivel del proveedor: los proveedores de catálogo fijo rechazan un literal no reconocido, mientras que los proveedores de catálogo dinámico, como Codex/OpenCode, aceptan un token sintácticamente válido. Un valor no compatible con el modelo elegido NO se rechaza aquí: el daemon comprueba su catálogo de modelos local en tiempo de ejecución, registra una advertencia y omite la sobrescritura incompatible.

Configúralo desde la CLI con --thinking-level al crear y actualizar un agente, al igual que con --model: el indicador es un simple paso al campo de nivel superior thinking_level, y al actualizarlo, una cadena vacía (--thinking-level "") lo restablece al valor predeterminado del tiempo de ejecución. La CLI no enumera deliberadamente los niveles válidos, ya que son específicos del tiempo de ejecución y del modelo (Claude utiliza actualmente low|medium|high|xhigh|max; los valores de Codex se obtienen del catálogo de modelos del tiempo de ejecución). Reenvía el token, el servidor aplica la enumeración fija o la puerta de token seguro del proveedor, y el daemon realiza la comprobación exacta del modelo y el nivel. Un entorno de ejecución cuyo proveedor no tenga el concepto «thinking» rechaza cualquier valor no vacío con un 400.

service_tier es el control de velocidad de Codex de primera clase correspondiente. Configúralo con --service-tier al crear o actualizar; utiliza --service-tier "" al actualizar para borrarlo. El catálogo de modelos del entorno de ejecución contiene tanto la copia de disponibilidad como la de visualización (actualmente «priority», que se muestra como «Fast»). El servidor acepta ID de catálogo de Codex futuros seguros, mientras que el daemon verifica el par exacto de modelo/nivel antes de la ejecución y omite cualquier anulación obsoleta e incompatible. Los agentes sin un modelo explícito fallan en estado cerrado porque se desconoce el modelo efectivo de config.toml.

modelo frente a custom_args

«model» es una columna persistente de primera clase que el demonio lee directamente. «custom_args» son argumentos sin procesar de la CLI del proveedor. La ayuda de la CLI señala que algunos proveedores (codex app-server, openclaw) rechazan «--model» dentro de «custom_args», pero se trata de una recomendación documentada de la CLI, no de una invariante impuesta por el servidor; nada en el controlador de creación inspecciona «custom_args» en busca de un indicador de modelo.

Entorno y secretos

`custom_env` contiene información confidencial. La CLI ofrece tres canales de entrada; dos mantienen los secretos fuera del historial del shell y de la lista de procesos:

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 lee el objeto JSON desde la entrada estándar; --custom-env-file lo lee desde un archivo (se recomienda el modo 0600). El tercer canal, --custom-env , coloca el valor en la línea de comandos, donde el historial del shell y el comando ps pueden verlo; evítalo para secretos reales.

Datos sobre la lectura (estas son las suposiciones erróneas que hay que evitar):

• Los recursos del agente nunca exponen custom_env en texto plano. Las operaciones list/get/create/update del agente y los eventos de WS solo devuelven has_custom_env (bool) y custom_env_key_count (int).
• Para leer valores en texto plano es necesario utilizar el punto final GET /api/agents/{id}/env (multica agent env get). Su acceso está restringido a los propietarios y administradores del espacio de trabajo, y se deniega a los agentes independientemente del rol del miembro que los respalde: un agente en ejecución no puede leer los secretos de otro agente.
• La escritura de valores tras la creación NO se realiza a través de la actualización del agente. El gestor genérico de actualizaciones rechaza cualquier campo «custom_env» con un código 400 («utiliza PUT /api/agents/{id}/env»). Las escrituras de entorno en texto plano se gestionan mediante PUT /api/agents/{id}/env (configuración del entorno del agente de Multica), que es de uso exclusivo del propietario o administrador y genera una entrada de auditoría.

mcp_config

mcp_config es la configuración del servidor MCP del agente (un objeto JSON como {"mcpServers": {…}}). También se trata de información confidencial —las entradas MCP suelen incluir tokens de API— y ofrece los mismos tres canales de entrada que custom_env, tanto enla creación como en la actualización del 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'   # borra la configuración

--mcp-config-stdin / --mcp-config-file mantienen el valor fuera del historial del shell y de ps; la opción en línea --mcp-config no lo hace. La CLI requiere unobjeto JSON o el valor literal null; un array de nivel superior o un tipo primitivo se rechaza en el lado del cliente, y una entrada vacía de stdin o de un archivo genera un error en lugar de borrarse silenciosamente.

Hay dos diferencias entre mcp_config y custom_env:

• SÍ se puede configurar mediante la actualización del agente. A diferencia de custom_env, mcp_config no tiene un punto final auditado específico: el PUT genérico /api/agents/{id} lo acepta. Tres estados según el cuerpo de la solicitud sin procesar: campo omitido → sin cambios; null → borrar; objeto → sustituir.
• Se serializa al leerlo, pero se censura.Las llamadas get/list del agente devuelven mcp_config solo a los usuarios autorizados a ver los secretos del agente; en caso contrario, el campo es nulo y mcp_config_redacted es verdadero. Los actores del agente nunca lo ven, y un espacio de trabajo puede forzar la censura para todos.

La compatibilidad de los proveedores no es uniforme: Qwen Code acepta un mcp_config gestionado a través de un archivo JSON temporal 0600 propiedad del daemon, pasado con --mcp-config; se elimina al finalizar la ejecución. Deja el campo sin definir (nulo) para heredar la configuración nativa de Qwen Code.

Asignación de habilidades

La creación de un agente NO vincula ninguna habilidad del espacio de trabajo; la vinculación es una llamada independiente que se realiza una vez creado el agente. Hay dos verbos distintos:

• add es aditivo: fusiona los ID proporcionados con las vinculaciones existentes (POST /api/agents/{id}/skills/add).
• set sustituye todo: sobrescribe toda la lista de vinculaciones exactamente por los identificadores proporcionados (PUT /api/agents/{id}/skills); --skill-ids '' borra todo.

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

En el momento de la solicitud, el demonio agrupa PRIMERO las habilidades del agente como habilidades vinculadas al espacio de trabajo y, a continuación, añade las habilidades integradas en la plataforma. LoadAgentSkills carga el contenido de cada habilidad vinculada junto con sus archivos de apoyo; las habilidades integradas se incorporan en tiempo de compilación y se cargan desde SKILL.md y los archivos relacionados. Ambas llegan al proveedor como contenido de la habilidad, razón por la cual la capacidad debe figurar en una habilidad vinculada, y no pegarse en las instrucciones.

Efectos secundarios que requieren aprobación

Solo lectura (seguro): obtener agente, lista de habilidades del agente, obtener entorno del agente.

Que modifican el estado (requieren una instrucción explícita; no se deben ejecutar de forma especulativa):

• creación de agente multica: inserta una nueva fila de agente.
• multica agent skills add / set: modifica los enlaces (set es destructivo: elimina los enlaces que no están en la nueva lista).
• multica agent env set — sobrescribe todo el mapa custom_env y escribe una fila de auditoría.

Supuestos erróneos habituales

• «La descripción es la línea de comandos». No es así: solo las instrucciones llegan al entorno de ejecución. Una descripción detallada con instrucciones vacías da lugar a un shell con nombre pero sin contrato operativo.
• «Create vincula las habilidades del agente». No es así; hay que vincularlas explícitamente después.
• «La actualización del agente puede rotar el entorno». No es así: devuelve un error 400 en ` custom_env`; utiliza el punto final del entorno.
• «mcp_config se comporta como custom_env al actualizar». No es así: mcp_config SE PUEDE configurar mediante agent update (--mcp-config), con --mcp-config nulo para borrarlo; solo custom_env está restringido tras el punto final dedicado a env.
• «La consultaget del agente muestra los valores de env». Solo muestra has_custom_env y custom_env_key_count.
• «Se detecta una combinación inválidade thinking_level/model al crearlo». Solo se detecta un literal desconocido a nivel de proveedor; las discrepancias específicas del modelo fallan en tiempo de ejecución.
• «set y add son intercambiables para las habilidades». set sustituye todos los enlaces; si se utiliza cuando se pretendía usar add, se eliminan silenciosamente las capacidades.

Referencias

references/creating-agents-source-map.md asigna cada contrato anterior a su archivo:línea en el árbol actual, el efecto en tiempo de ejecución y un comando de verificación seguro de solo lectura .