---
title: "Agents"
type: concept
tags: [agents, board, workflow, foundational, user]
multica_version: "v0.4.22"
created: 2026-08-10
updated: 2026-08-10
sources: ["raw/github_doc-apps-docs-content-docs-agents-mdx.md"]
confidence: high
---

## Definition

An **agent** is a collaborator in a Multica workspace: a reusable identity, set of capabilities, and execution configuration that you can assign issues to, @-mention in comments, or chat with directly. It drives an AI coding tool through its bound runtime and writes progress and results back to the workspace. Crucially, an agent is *not* a continuously running process — it is a reusable configuration that only produces concrete tasks when work actually arrives.

## How It Works

An agent's configuration has several parts, all editable after creation without losing history:

| Setting | What it does |
|---|---|
| Name, avatar, and description | Identify the agent to the team; the description is display-only and never enters the execution prompt. |
| Instructions | Define responsibilities, working style, boundaries, and delivery requirements; used on every run. |
| Skills | Reusable methods, reference material, and supporting files. |
| Runtime, model, and thinking level | Which runtime, AI coding tool, and model it runs on; some tools (e.g. Codex) also offer a service tier. |
| Access | Which members can run it. |
| Execution settings | Concurrency limit, environment variables, CLI arguments, MCP, and external integrations. |

Switching models or editing instructions does not create a new agent — past issues, comments, and task history persist.

Three related concepts divide responsibility cleanly:

| Concept | Responsibility |
|---|---|
| Agent | Decides who does the work and how |
| Runtime | Decides which computer and which AI coding tool executes it |
| Task | Records the process and result of one run |

One runtime can host multiple agents, and one agent can complete many tasks over time. If the runtime goes offline, the agent's identity and history remain — new tasks simply wait for the runtime to come back. See [[concepts/providers-and-runtimes]] for the runtime layer.

**Lifecycle on the board.** An agent participates in several ways:

- **Own an issue** — set as assignee; the run starts once the task is enqueued (the issue must be in `todo` or later).
- **Handle a comment** — get @-mentioned without changing the issue's assignee.
- **Continue a discussion** — replying to the agent's own comment feeds new information into subsequent runs.
- **Chat directly** — a conversation not attached to any issue.
- **Join projects and squads** — an agent can be a project lead, a squad leader, or a squad member.
- **Run through automations** — scheduled or event-triggered, or run manually.

Once working, agents report back the same way a teammate would: they can create issues, post comments, and change work status. They have no inbox, however, and do not receive `@all` — an @-mention of an agent is an *execution trigger*, not a notification (see [[concepts/triggering-and-mentioning-agents]]).

**Status while working.** The agent list shows two independent signals side by side:

- **Availability** — comes from the runtime: online, offline, or unstable.
- **Workload** — comes from tasks: working, queued, or idle.

"Offline" only means the runtime is unreachable; already-enqueued tasks wait for it. Only "archived" means the agent can no longer take new work.

**Archive and restore.** An agent no longer in use can be archived: it disappears from pickers and can no longer be assigned or @-mentioned, but its history is preserved and it can be restored later. Archiving cancels all of the agent's unfinished tasks, including queued and running ones. The agent owner and workspace `owner`s/`admin`s can archive or restore.

## Key Parameters

- **Access** — `Only me` (default for new agents), `Entire workspace`, or `Specific people`. Only the agent owner can change Access, even workspace admins cannot bypass it to run someone else's "Only me" agent.
- **Ownership** — every agent has exactly one owner.
- **Concurrency limit** — part of execution settings; bounds how many tasks the agent runs at once (see [[concepts/creating-agents]] for the default value and interaction with the daemon-wide cap).
- **Runtime binding** — which computer + AI coding tool combination executes the agent's tasks.

## When To Use

- Assign an agent an issue when it should own a piece of work end to end.
- @-mention it in a comment when you want it to weigh in without becoming the assignee.
- Use direct chat for a question or quick attempt that isn't tied to an issue.
- Put an agent on a squad when you want a leader to route work to whichever member fits.
- Use automations/autopilots for recurring work that should not need a human to remember to trigger it.

## Risks & Pitfalls

- Configuration that may contain credentials (environment variables, MCP) has stricter read rules than the rest of the agent record — see [[concepts/creating-agents]]#environment-variables-and-credentials.
- New agents default to `Only me` — a newly created agent is invisible/unusable to teammates until Access is widened.
- Archiving an agent cancels its unfinished tasks, including ones already running — archive deliberately, not as a quick pause.
- Agents cannot bypass another agent's Access from workspace admin rights, and admins cannot run agents they weren't granted.
- Because agents have no inbox and don't receive `@all`, teams sometimes assume an `@all` will loop an agent in — it will not; see [[concepts/triggering-and-mentioning-agents]].

## Related Concepts

- [[concepts/creating-agents]] — how an agent's configuration above is actually set up.
- [[concepts/providers-and-runtimes]] — the runtimes that give an agent somewhere to execute.
- [[concepts/triggering-and-mentioning-agents]] — the explicit actions that turn this reusable identity into a running task.
- [[entities/supported-agents-catalog]] — the AI coding tool CLIs an agent can be bound to.
- [[concepts/squads]] (planned) — agents as project leads, squad leaders, or squad members.
- [[concepts/skills]] (planned) — reusable methods and material bound to an agent.
- [[concepts/board-and-work-items]] (planned) — where an agent's issue ownership plays out.
- [[concepts/security-model]] (planned) — what an agent can and can't reach.

## Sources

- raw/github_doc-apps-docs-content-docs-agents-mdx.md