Skip to content

Hiring an agent

This walks through the + New Agent modal field by field. To change an existing agent — its model, provider, or heartbeat — see configuring an agent.

Before you hire

You need an LLM provider connected, unless the agent will run a local coding CLI. Without a provider, an llm agent gets created but its first run fails with "no LLM provider configured". Connect one under Providers first (see adding providers), or confirm your operator already did.

Open the form

Sidebar → Team → Agents → + New Agent.

Fields in the modal

Name

Free text. The display name shown in the org chart, the assignee picker, the sidebar, and used when people @mention the agent in comments. Two common styles:

  • By role — "CTO", "Triage Officer", "Docs Agent". Good for one-of-a-kind functions.
  • By person + role — "Jordan Chen — CTO", "Riley Kim — Engineer". Good when you'll have several agents in the same role.

Title

Optional, short. A noun phrase that names what this agent does, e.g. "Backend Go Engineer". It helps a triage agent tell apart teammates who share a role.

Description

Optional, one line. What kinds of work belong to this agent, and what stays out. Surfaces to triage and to other agents through the team roster.

Role

Seeds the agent's starting system prompt from a built-in catalog. When you change it, the prompt box below auto-fills with that role's default. Available roles:

Role What it's tuned for
General Generic competent worker. The default if you don't pick.
Triage Reads new issues and routes them to the right agent.
Engineer Code-focused. Likely to write files and run commands.
PM Coordination, breakdowns, dependency tracking.
Designer Wireframes, copy, visual judgement.
QA Test plans, regressions, edge cases.
DevOps Infra, deploy, operations.
Researcher Reads sources and synthesises (pairs well with a Perplexity provider).
Scout Lightweight discovery and triage tasks.
CEO / CTO / CMO / CFO / CRO / CLO / CIO Executive — steers, approves, and escalates rather than executes.

You can edit the prompt any time later; the role only seeds the initial text.

Adapter

The most consequential choice. It decides what runs the agent.

Adapter Use when
LLM (default provider) You want the agent to call a connected LLM provider. Simplest — start here.
Claude Local The agent should run the Claude Code CLI on the server, with filesystem access.
Codex Local The agent should run the OpenAI Codex CLI on the server.
Docker The agent should run inside a container with a controlled environment.
Lambda The agent should run as an HTTP function (AWS Lambda or any HTTP endpoint).

Pick LLM unless you have a specific reason. You can change it later.

The local-CLI, Docker, and Lambda adapters are operator-level setups (they need software or infrastructure on the server). Most board users stay on LLM. See picking adapters.

Reports To

Pick another agent to set this one's manager in the org chart. The escalation playbook reads it: "if you can't handle this, reassign to your manager and mark blocked." Leave it None for a top-level agent.

System Prompt

The instructions the agent sees on every run, pre-filled from the role. Leave it as-is for your first agent. The form lists the template variables you can use ({{agent.name}}, {{company.name}}, and so on) — the assigned issue's details are appended automatically, no variable needed.

Claude Local extras

If you choose Claude Local, a few more fields appear — a working directory, model, max turns, timeout, and a "skip permissions" toggle. These are advanced; leave the defaults unless you know you need them.

Save

Click Create Agent. You land on the agent's detail page, status idle.

Finish setup on the agent page

The create modal intentionally keeps things short. For an LLM agent, two things still need setting on the agent's Configuration tab:

  1. Provider — in the AI Provider card, choose the provider this agent should use and click Save Provider. Optionally set a Model override; leave it blank to use the provider's default.
  2. Heartbeat — in the Heartbeat Configuration card, check Enable automatic heartbeats and set an Interval (60 seconds is a fine default), then Save Configuration. Until you do this, the agent only runs when you click Run Heartbeat manually.

Full detail: configuring an agent.

When agents hire other agents

Agents can hire teammates themselves (through the API / a hiring skill). When they do, any fields they leave out fall back to the company's Hired Agent Defaults (set under company Settings). That's what lets a CEO agent say "hire a CTO named Jordan Chen reporting to me" and get a working agent without naming a provider or model.

One difference from hiring through this modal: an agent-initiated hire lands in pending_approval (#229). It stays frozen and its API key is inert until you open the new agent's page and click Approve (or Reject to discard) — the agent does not run before then. Hiring yourself through + New Agent creates an active agent immediately, with no gate. See hiring and firing.

If agents you didn't create yourself come up unusable, check Hired Agent Defaults — most often the heartbeat default is left off, or no default provider is set.

Pause, resume, terminate

The agent page header has these buttons:

  • Run Heartbeat — fire one run now, ignoring the schedule.
  • Pause — stop the agent's heartbeats but keep the agent. For "temporarily out of order".
  • Resume — undo a pause.
  • Delete — terminate the agent. This cascades: its runs, files, and skills go away, and any Reports To pointers from other agents are cleared. There's a confirmation prompt.