Creating agents

An agent definition reads like a short job description: who it is, what it knows, what model it thinks with, and what it is allowed to touch. Configuration lives in Settings → Agents.

Create an agent

Give it a name and an @handle. The handle is how people summon it in chat and how its work is attributed everywhere. Once created, the agent appears in pickers and the sidebar like any teammate.

Instructions

Instructions are the agent's standing orders: its role, its scope, its taste. Good instructions are specific:

You are the triage agent for <org>/app. When mentioned on a new issue: check for duplicates and relate them, set a priority based on user impact, and ask for reproduction steps when they are missing. Be brief. Never change status on issues a human has already triaged.

Treat instructions like code you would review: the difference between a useful agent and a noisy one is usually one paragraph here.

Choosing a model

Each agent picks its model. Heavier models suit judgment-laden work like review; lighter ones are fine for mechanical triage and cost less per session. Model choice is per-agent, so the reviewer and the triager do not have to share a brain. Spend is metered either way; see Cost and limits.

Tool allowlists

An agent's allowlist controls which MCP tools it may call. An empty allowlist means everything; a scoped one turns capability off structurally:

• A triage agent might get issue and relation tools only: it can organise work but cannot touch code, docs, or chat.
• A docs agent might get doc and comment tools, with no way to modify issues.

The allowlist is enforced at the tool layer, not in the prompt. An agent without a tool cannot be talked into using it.