multica-creating-agents

Создание агентов Multica

Это соглашение, описывающее процесс создания агентов Multica: что принимают точки входа create, что сервер проверяет и отклоняет, как каждое поле сохраняется, и какие поля демон фактически считывает при обработке заявки. Это не руководство по параметрам — здесь излагаются факты, отслеженные по исходному коду, и каждое утверждение подтверждается указанием «файл:строка» в файле references/creating-agents-source-map.md.

Быстрый старт (просмотр только для чтения)

Эти команды считывают состояние и не имеют побочных эффектов:

multica agent get  --output json      # полная сохраненная запись агента
multica agent skills list  --output json   # текущие привязки навыков
multica agent env get  --output json  # среда в виде обычного текста (только для владельца/администратора, агентам доступ запрещен)

Команда `agent get` возвращает сохраненные данные агента, включая `runtime_id`, `model`, `thinking_level`, `service_tier`, `custom_args`, `has_custom_env`, `custom_env_key_count` и навыки. Она никогда не возвращает `custom_env` в виде открытого текста.

Базовая модель

Агент представляет собой строку в пределах рабочего пространства (таблица agent). Создание осуществляется одним POST-запросом на /api/agents (multica agent create). Во время получения задачи демон повторно считывает строку агента и формирует рабочий набор данных — таким образом, агент работает на основе сохраненных полей, а не на основе данных, сгенерированных во время создания.

Два разных текстовых поля, которые часто путают:

• description — это краткое описание из каталога. Оно хранится и отображается в списках; демон НЕ вставляет его в подсказку агента во время выполнения. Рассматривайте его исключительно как метаданные, предназначенные для человека. Максимальный размер — 255 кодовых точек Unicode.
• instructions — это договор о поведении во время выполнения. Демон считывает его в момент запроса и отправляет провайдеру в качестве постоянных инструкций агента. Здесь указываются роль, обязанности, границы, правила вывода и эскалации, а не в поле description.

Точки входа CLI / API

Минимальный вызов для создания (оба параметра —--name и --runtime-id — обязательны):

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

Команда runAgentCreate формирует тело запроса в формате JSON и отправляет его на /api/agents. Она добавляет ключ только в том случае, если был указан соответствующий флаг —description/instructions с непустое значение, остальные (runtime-config, custom-args, model, thinking-level, service-tier, visibility и т. д.) — при изменении соответствующего флага; таким образом, пропущенные флаги принимают значения по умолчанию сервера, а не отправляют пустые строки.

Тело HTTP-запроса (CreateAgentRequest) принимает следующие параметры: name, description, instructions, avatar_url, runtime_id, runtime_config, custom_env, custom_args, model, thinking_level, service_tier, visibility, max_concurrent_tasks, mcp_config.

Контракты по полям

Значения по умолчанию при отсутствии: runtime_config → {}, custom_env → {}, custom_args → [], avatar_url → случайный смайлик:, visibility → private, max_concurrent_tasks → 6 (все материализуется на стороне сервера перед вставкой).custom_args/runtime_config имеют типы []string/any и маршалируются без изменений — отклонение из-за несоответствия структуре JSON происходит в CLI, а не в обработчике создания.

thinking_level проверяется только на уровне провайдера: провайдеры с фиксированным каталогом отклоняют нераспознанный литерал, в то время как провайдеры с динамическим каталогом, такие как Codex/OpenCode, принимают синтаксически безопасный токен. Значение, не поддерживаемое для выбранной модели, здесь НЕ отклоняется — демон проверяет свой локальный каталог моделей во время выполнения, записывает предупреждение в журнал и пропускает несовместимое переопределение.

Устанавливайте его из CLI с помощью --thinking-level при создании и обновлении агента, аналогично --model: этот флаг является простым проходом к полю thinking_level верхнего уровня, а при обновлении пустая строка (--thinking-level "") сбрасывает его обратно к значению по умолчанию среды выполнения. CLI намеренно не перечисляет допустимые уровни — они зависят от среды выполнения и модели (Claude в настоящее время использует low|medium|high|xhigh|max; значения Codex определяются из каталога моделей среды выполнения). Он пересылает токен, сервер применяет фильтр провайдера с фиксированным перечнем или безопасным токеном, а демон выполняет точную проверку модели/уровня . Среда выполнения, провайдер которой не поддерживает концепцию «thinking», отклоняет любое непустое значение с кодом ошибки 400.

service_tier — это соответствующий первоклассный регулятор скорости Codex. Устанавливайте его с помощью --service-tier при создании/обновлении; используйте --service-tier "" при обновлении, чтобы очистить его. Каталог моделей среды выполнения содержит как копию доступности, так и копию для отображения (в настоящее время приоритет, отображаемый как Fast). Сервер принимает безопасные будущие идентификаторы каталогов Codex, в то время как демон проверяет точную пару «модель/уровень» перед выполнением и игнорирует устаревшее несовместимое переопределение. Агенты без явно указанной модели завершают работу с ошибкой, поскольку эффективная модель в файле config.toml неизвестна.

модель против custom_args

«model» — это первоклассный сохраняемый столбец, который демон считывает напрямую. custom_args — это необработанные аргументы CLI провайдера. В справке CLI отмечается, что некоторые провайдеры (codex app-server, openclaw) отклоняют --model внутри custom_args — но это документированное руководство по CLI, а не навязываемое сервером ограничение; ничто в обработчике create не проверяет custom_args на наличие флага model.

Среда и секретные данные

`custom_env` — это секретная информация. CLI предлагает три канала ввода; два из них не сохраняют секреты в истории командной оболочки и списке процессов:

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 считывает объект JSON из стандартного ввода; --custom-env-file считывает его из файла (рекомендуемый режим 0600). Третий канал, --custom-env , помещает значение в командную строку, где его могут увидеть история команд оболочки и команда ps — избегайте его для действительно секретных данных.

Факты со стороны чтения (это ошибочные предположения, которых следует избегать):

• Ресурсы агента никогда не раскрывают custom_env в виде открытого текста. Команды agent list/get/create/update и события WS возвращают только has_custom_env (bool) и custom_env_key_count (int).
• Для чтения значений в виде открытого текста требуется специальный конечный пункт GET /api/agents/{id}/env (multica agent env get). Доступ к нему ограничен владельцемрабочей области или администраторами, а участникам-агентам доступ запрещен независимо от роли участника, стоящего за ними — работающий агент не может читать секреты другого агента.
• Запись значений после создания НЕ осуществляется через обновление агента. Общий обработчик обновлений отклоняет любое поле custom_env с кодом ошибки 400 («используйте PUT /api/agents/{id}/env»). Запись значений среды в виде открытого текста обрабатывается с помощью PUT /api/agents/{id}/env (multica agent env set), доступным только владельцу или администратору и записывающим строку в журнал аудита.

mcp_config

mcp_config — это конфигурация сервера MCP агента (объект JSON, например {"mcpServers": {…}}). Это также конфиденциальная информация — записи MCP обычно содержат токены API — и предоставляет те же три канала ввода, что и custom_env, как при создании агента, так и при его обновлении:

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'   # очищает конфигурацию

--mcp-config-stdin / --mcp-config-file не сохраняют значение в истории команд оболочки и в ps; встроенный параметр --mcp-config этого не делает. CLI требует JSON- объекта или литерала null; массив верхнего уровня или примитивный тип отклоняются на стороне клиента, а пустой ввод из stdin/файла приводит к ошибке, а не к бесшумному сбросу.

Два отличия mcp_config от custom_env:

• Его МОЖНО настроить посредством обновления агента. В отличие от custom_env, mcp_config не имеет выделенного контролируемого конечного пункта — его принимает общий PUT /api/agents/{id} . Три состояния в зависимости от исходного тела запроса: поле опущено → без изменений; null → очистка; объект → замена.
• Оно сериализуется при чтении, но подвергается редактированию. Агентскиезапросы get/list возвращают mcp_config только вызывающим сторонам, имеющим право просматривать секретные данные агента; в противном случае поле равно null, а mcp_config_redacted равно true. Агентские объекты никогда не видят его, а рабочая область может принудительно применить редактирование для всех.

Поддержка провайдерами не унифицирована: Qwen Code принимает управляемый mcp_config через временный JSON-файл с правами 0600, принадлежащий демону и передаваемый с параметром --mcp-config; он удаляется при завершении выполнения. Оставьте поле не заданным (null), чтобы унаследовать нативные настройки Qwen Code.

Привязка навыков

Создание агента НЕ приводит к привязке каких-либо навыков рабочей среды — привязка осуществляется отдельным вызовом после создания агента. Используются два разных метода:

• add — аддитивный: он объединяет указанные идентификаторы с существующими привязками (POST /api/agents/{id}/skills/add).
• set — замена всего списка: перезаписывает весь список привязок именно указанными идентификаторами (PUT /api/agents/{id}/skills); --skill-ids '' очищает все.

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

Во время обработки запроса демон сначала собирает навыки агента как навыки, привязанные к рабочей области, а затем добавляет встроенные навыки платформы. LoadAgentSkills загружает содержимое каждого привязанного навыка вместе с сопутствующими файлами; встроенные навыки встраиваются на этапе компиляции и загружаются из SKILL.md и сопутствующих файлов. Оба варианта поступают к провайдеру в виде содержимого навыка — именно поэтому функциональные возможности должны находиться в привязанном навыке, а не вставляться в инструкции.

Побочные эффекты, требующие одобрения

Только для чтения (безопасно): получение агента, список навыков агента, получение среды агента.

Изменяющие состояние (требуют явной инструкции — не запускать спекулятивно):

• multica agent create — вставляет новую строку агента.
• multica agent skills add / set — изменяет привязки (команда set является деструктивной: она удаляет привязки, отсутствующие в новом списке).
• multica agent env set — перезаписывает всю карту custom_env и записывает строку аудита.

Распространённые ошибочные предположения

• «Описание — это подсказка». Это не так — в среду выполнения попадают только инструкции. Подробное описание с пустыми инструкциями приводит к созданию именованной оболочки без рабочего контракта.
• «Create связывает навыки агента». Это не так; связывайте их явно позже.
• «Команда agent update может менять env». Это невозможно — она возвращает ошибку 400 при попытке изменить custom_env; используйте конечную точку env.
• «mcp_config ведет себя как custom_env при обновлении». Это не так — mcp_config МОЖНО настроить с помощью agent update (--mcp-config), причем --mcp-config с нулевым значением служит для очистки; только custom_env защищен специальным конечным пунктом env.
• «Командаagent get отображает значения env». Она отображает только has_custom_env и custom_env_key_count.
• «Недопустимая комбинацияthinking_level/model выявляется при создании». Выявляется только неизвестный литерал на уровне провайдера — пробелы, специфичные для модели, приводят к сбоям во время выполнения.
• «Командыset и add взаимозаменяемы для навыков». Команда set заменяет все привязки; использование её вместо add незаметно удаляет возможности.

Ссылки

Файл references/creating-agents-source-map.md сопоставляет каждый из приведённых выше контрактов с его номером файла и строкой в текущем дереве, эффектом во время выполнения и безопасной командой проверки, доступной только для чтения. »