Create and configure an agent

Creating an agent requires a working runtime first. The runtime decides which computer and which AI coding tool the agent uses; the agent holds the long-lived identity, instructions, and capabilities.

On the workspace Agents page, click New agent.

Starting points

The creation page offers two options:

Build with AI needs an online runtime for the Builder conversation. Either way, you can review and edit the final configuration before creating.

Required fields

Creating an agent requires only two things:

• Name — must be unique within the workspace.
• Runtime — the environment that actually executes tasks.

Every other field can start with its default and be adjusted after creation. By default, only the creator can run a new agent.

Description and instructions

The description is a short introduction for the team. It appears only in the agent list and detail page, and never enters the AI coding tool's prompt.

Instructions are provided to the agent on every run and usually cover:

• what it is and isn't responsible for;
• what to check first when work arrives;
• what it is allowed to modify;
• how to deliver results;
• when to check with a member before proceeding.

For example:

You review frontend pull requests.

Read the diff and related tests first, and check only:
- React and TypeScript correctness
- Accessibility
- Consistency with existing component patterns

Do not modify code directly. Post findings in an issue comment,
ordered by severity; when nothing blocks, state clearly that the change can merge.

Adding skills

During creation you can pick one or more skills from the workspace.

Skills suit methods and material reused across agents; long-lived requirements that belong only to this agent go in the instructions.

Runtime, model, and thinking level

Each runtime already maps to one AI coding tool. After picking a runtime, you can pick a model and thinking level the tool supports; some tools (such as Codex) also offer a service tier:

• Left blank, the runtime or local CLI default applies.
• With a model set, the agent uses that override for tasks it picks up afterwards.
• Some runtimes manage models themselves, so no model picker is shown.

Tools differ in supported models, session resume, skills, and MCP capabilities — see AI coding tools comparison.

Access

Access decides which members can run this agent (assign, @-mention, or chat):

Only the agent owner can change Access — workspace admins cannot. Workspace owners and admins can manage the rest of the configuration, but cannot use their admin role to run agents they aren't granted.

Configuration after creation

On the agent's detail page you can keep adjusting:

The daemon hosting the runtime also has a global concurrency cap (default 20); the effective concurrency is the smaller of the two.

Editing configuration does not change tasks already running. Later tasks use the agent configuration saved at the time the runtime picks them up.

Environment variables and credentials

Environment variables suit limited-privilege credentials the agent needs at run time, such as a read-only API key or a single-scope token.

Do not use production database admin passwords or other high-value long-lived credentials.

Critical runtime variables such as PATH, HOME, and MULTICA_* cannot be overridden here.

Custom arguments and MCP

Custom arguments are passed to the AI coding tool as an array, item by item, without shell expansion. Whether an argument is valid is up to the tool; model configuration that already has a dedicated field doesn't need to be repeated here.

MCP configuration may contain tokens; its storage and display rules match environment variables. Only runtimes that support managed MCP configuration show this section; tools without MCP support don't gain it just because a configuration is saved.

Duplicating an agent

Duplicating carries over most working configuration except the name, including instructions, skills, custom arguments, avatar, concurrency limit, and Access settings. The model, thinking level, and service tier come along too; if the original runtime is unavailable and the copy is forced onto another runtime, those three are cleared and must be re-selected.

Environment variable values and MCP configuration are never copied and must be set again on the new agent. Duplication keeps the original agent's runtime binding and Access settings.

Creating with the CLI

multica agent create \
  --name "Frontend Reviewer" \
  --runtime-id <runtime-id> \
  --description "Reviews frontend pull requests" \
  --instructions "Read the diff and tests first; post review conclusions only as issue comments."

Plaintext in command-line arguments ends up in shell history; stdin and permission-restricted files do not.

When a similarly configured agent already exists, copy it directly:

multica agent copy <agent-id>

By default the copy stays on the same runtime; add --runtime-id to move it to another runtime, which also requires --model. Environment variables, MCP configuration, and runtime_config are never copied; the runtime binding itself is kept. Full flags in Using the CLI.

Next steps

• Assign issues to agents — validate the configuration with real work.
• Skills — create, import, and reuse team methods.
• Daemon and runtimes — troubleshoot online status and where execution happens.