Multica / agent

Create and configure agents

The minimum fields to create an agent, as well as all optional configuration items - system directives, environment variables, visibility, concurrency limit, and archiving mechanism.

View official source Docs index

Create and configure agents key concepts infographic

Overview

Creating an agent requires only two things: a name and choosing an AI programming tool. Everything else is optional - system commands, models, environment variables, command line parameters, visibility, concurrency limit - the default values can be used. Run it first and then adjust it slowly. All fields can be changed at any time.

Create an agent

Prerequisite: You have installed at least one supported AI programming tool (Claude Code, Codex, etc.) on your machine and have a daemon running. If you haven't gotten this far yet, take a look at Cloud Quick Start or Self-Deployment Quick Start.

After you are satisfied, click + New on the Agent page of the workspace, or use the command line:

multica agent create

There are only two required fields in the form: Name (unique in the workspace) and Runtime (= choose an AI programming tool). Other fields are discussed one by one below.

Choose an AI programming tool

Behind the runtime is a concrete AI programming tool. Multica supports 12 models, the most commonly used ones:

Tools	Fit
Claude Code	Anthropic official, with the most complete functions; First choice for newbies
Codex	OpenAI, mainstream alternative
Cursor	Cursor editor eco-user
Copilot	Teams using GitHub account benefits
Gemini	Google Eco User

For the other 7 (Antigravity, Hermes, Kimi, Kiro CLI, OpenCode, Pi, OpenClaw) and the complete capability differences of each tool (session recovery, MCP, skill injection path, model selection), see AI Programming Tool Comparison.

Write system commands

System instructions (instructions) will be spelled at the beginning of each task, telling the agent what role it plays and what rules it follows:

You are a front-end code review agent. When you get the issue, read the diff first and focus only on:
- Style issues (tailwind class name, box model)
- Accessibility (a11y)
Don't change the code, just give suggestions in the comments.

When left blank (default), the agent uses the native behavior of the AI programming tool behind it, with no additional constraints.

Select model

Most AI programming tools support model selection (for example, Claude Code can select in Sonnet / Opus). Leave blank → use the tool's own default; explicitly selected → use the selected one. For the models supported by each tool, see AI Programming Tool Comparison.

Changing the model will only take effect on new tasks**. Tasks that have been dispatched continue to use the model that was solidified when dispatched.

Custom environment variables (customenv)

Custom environment variables (customenv) allow you to inject additional env vars during task execution - typical uses are API keys or switching upstream endpoints:

ANTHROPIC_API_KEY = sk-...
ANTHROPIC_BASE_URL = https://my-proxy.example.com

Key system variables cannot be overwritten: PATH, HOME, USER, SHELL, TERM, CODEX_HOME, and any key starting with MULTICA_* will be silently ignored by the daemon process (there is a warn in the log, no error will be reported).

The value of **custom_env is stored in clear text in the Multica server database. ** The agent list/get interface no longer returns any env values - only the number of keys. Reading the real value requires the workspace owner/admin to call the dedicated and audited GET /api/agents/{id}/env (CLI: multica agent env get <id>). Even if the agent that is executing the task is the owner, it cannot read the env of other agents - this interface rejects the agent-actor session. The real value can still be seen in database backup and DB audit. Don't put high-value secrets into custom_env (production database passwords, root-level tokens, etc.). Use independent, limited-privilege credentials (read-only API key, single-scope PAT) for the agent, and rotate them regularly.

Custom command line parameters (customargs)

Custom command line parameters (customargs) are an array of strings that will be appended to the end of the command line of the AI programming tool one by one:

["--max-turns", "100", "--append-system-prompt", "always respond in Chinese"]

When finished, it will be:

claude --model <model> --max-turns 100 --append-system-prompt "always respond in Chinese" [...]

The parameters are passed as they are, without shell parsing (no injection risk), but whether the passed flag can be recognized depends on the AI programming tool itself - different tools vary greatly.

There is no hard limit for custom_env and custom_args, but actual usage is recommended to be within 10. Too many will make the command line longer, slower to start, and more difficult to maintain.

visibility

Create a new default private.

Visible workspace (workspace) - any member in the workspace can be assigned
Private (private) - Only the owner, admin of the workspace, or the creator of the agent can assign

Private does not mean hidden - All members in the list can see the name and description of the private agent, but they cannot see the sensitive configuration (the env value will never appear in the agent list/get response; MCP configuration will be coded for non-owners). For the complete meaning, see [Agent → Who can assign the agent](/vibe-coding-tools/multica/agents#Who can assign the agent).

Concurrency limit

The upper limit of concurrency (maxconcurrenttasks) determines how many tasks this agent can run at the same time. The default is 6. New tasks that reach the upper limit remain in the queue and will not be rejected.

This is just the "agent layer" of two limits - the daemon itself has a thicker limit (20 by default), and the tighter of the two takes effect. For details, see [Daemon Process and Runtime → How many tasks can be run concurrently at one time] (/daemon-runtimes#How many tasks can be run concurrently at one time).

Modifying this value will not cancel the task that is already running - it will only take effect on the next task to be taken away.

Hang professional knowledge: Skill

The created agent can be attached to Skill - a professional knowledge package (SKILL.md + supporting files), which will be automatically sent to the corresponding AI programming tool when the task is executed. You can create a new one, import it from GitHub/ClawHub, or scan it from the existing skill directory on your local machine. See Skills for details.

Archive and restore

An agent that is no longer used can be archived - it disappears from the daily view, but all historical data (tasks run, comments posted) are retained. Just restore it when you want to use it again.

Archiving will immediately cancel all unfinished tasks of this agent - those that are running, dispatched, and still queued will be marked as cancelled and will not continue to execute. If there is an important task running, let it be completed before filing it away.

Archived agents cannot be assigned new tasks.

Next step

Skills - attach professional knowledge package to the agent
AI Programming Tool Comparison - Complete capability differences of 12 tools
Assign issues to agents - How to use it after creating it