Skip to content

Set up an AI team with your agent

CLIAPIAdvanced~20 min

You want AI coworkers with names — an Iris who owns the API, a Dara who owns the server — so that when a pull request merges you can ask "who wrote this, and why" and get an answer instead of a shrug.

You do not have to build that yourself. Everything on this page is something you ask a coding agent to do: Claude Code, Codex, Cursor, or any other agent connected to Hadron. It runs the commands; you make the decisions and check the results.

If you would rather run the steps yourself, the same setup written as commands is in Set up an AI team. Nothing here is a simplified version of it — it is the same work, delegated.

What this gets you, in one paragraph

A worker is a named AI team member: a role agent (say, "Backend Engineer") cast into your team under a name. Iris is not a prompt file — she is an entity your work attaches to. Every coding session records which worker did it, which human drove it, which tool and model ran it, and where the transcript sits. So a merged PR leads back through a commit trailer to a worker, to its sessions, to the conversation that produced the code. The model behind it is Teams, workers, and sessions — worth ten minutes before you start, because two of the decisions below are permanent.

Before you start

  • An organization in Hadron, and ADMIN or OWNER in it.
  • A coding agent that can run shell commands, with the hadron CLI installed and authenticated. Claude Code, Codex and Cursor all qualify; the examples name none of them in particular.
  • A rough answer to "what roles does my team have?" — backend, frontend, review, docs. You can add more later.

An MCP-only agent cannot do the setup

Building a team creates Agents, publishes imports, installs an App and adds members — and none of those operations exist as MCP tools. An agent connected to Hadron over MCP alone can cast workers and drive sessions, but it cannot create the team for them to be cast into. Asks 1–3 below need the CLI or the GraphQL API.

This flips after setup: once the team exists, the day-to-day loop — binding a worker session, posting to the team chat, recording milestones — is entirely MCP-native, which is why most of this team works from a desktop app with no terminal at all.

The shape of the conversation

Five asks, in order. After each one, check the result before moving on — the "How to know it worked" lines are the point of this page, not the phrasing of the requests.

1. Ask for the team container

"Create a Team Agent in my org acme.com called Platform Team, and add role definitions for backend-engineer, frontend-engineer and reviewer."

How to know it worked. Ask your agent to read the roles back. You should see one definition per role, each with a description and nothing else — role definitions do not allocate names, they just say the role exists.

2. Ask for one agent per role

"Create a role agent for each of those roles. Give each one a persona prompt written in the second person, describing what that role owns and how it works. Use {{name}} where the worker's name should appear."

This is the ask worth spending time on. The persona prompt is what your workers will actually be — the rest of this page is plumbing. Read what your agent drafted and edit it. A vague prompt produces a vague coworker.

How to know it worked. Ask for each agent's persona prompt back and read it — you are checking that it says what you meant, and that {{name}} appears somewhere in it. A template that never binds the name silently produces workers whose prompt never names them.

Hadron has a field for exactly that check, hasNamePlaceholder, but it lives on the App-scoped surfaces — so it cannot answer until the App exists. The dry run in ask 4 reports it, which is the right moment anyway: that is where you see the composed prompt before anything is permanent.

3. Ask for the team to be installed as one App

"Bundle the role agents into the Team Agent and install it as an App called Platform Team, then add me to it."

How to know it worked. Ask for the App's URN and its installed agents. The App is a different entity from the Team Agent and has its own URN — if your agent hands you one identifier for both, something is wrong.

4. Cast the workers — this one is permanent

"Cast a worker named Iris as backend-engineer, and Dara as reviewer."

Two decisions here are yours and cannot be undone.

The names. A worker's name is permanent within the App, case-insensitively and forever. Retiring a worker never frees its name, because merged commit trailers and years of chat history refer to it. Choose names you will still want in a year, and agree them with your team first — Hadron does not allocate them for you and will not stop two people burning the same good name.

Casting is effectively irreversible. There is one escape and it is narrow: a worker that has never been used — no session ever bound, nothing in its working memory — can be removed outright, which does free its name. The moment it has any history that door closes (WORKER_IN_USE), and it retires instead, keeping its name forever. So a typo caught immediately is fixable; a name you regret next month is not.

Ask your agent to rehearse first anyway — Hadron has a dry run that performs the exact same resolution and refusals without writing anything, and shows you the composed prompt your worker would boot with, plus whether the template binds {{name}}. Read that prompt. It is the cheapest moment to change your mind, and the only one that costs nothing at all.

How to know it worked. Ask for the staff list, and ask for it including retired workers — the default listing hides them, and retired workers keep their names forever, so an unqualified list under-reports what is already taken.

5. Ask your agent to work as one of them

"Start a worker session as Iris, then post in the team chat that you are picking up issue 412."

How to know it worked. The chat message should be attributed to Iris, not to you. That is the whole feature: if the post lands under your own name, the session binding did not happen and the work will not be attributable either.

6. Ask for the work to be recorded

A bound session is not yet provenance. Two things close the loop, and an agent will skip both unless asked:

"As you work, record each milestone against the session — the PR you open, the commits you push. And sign the commits with the worker trailer."

The trailer is the part that survives. A commit carries Worker: Iris (backend-engineer) <hrn:worker:…>, which outlives a squash-merge where a branch name does not, and it is app-qualified because worker names are only unique within a team. That trailer is the thread the whole payoff hangs from — without it a merged PR leads back to nothing.

How to know it worked. Ask "which sessions produced this PR?" and give the ref. You should get several rows for a PR of any size — that is expected, not duplication — each carrying the worker, the human who drove it, the tool, the model, and the transcript path. If you get nothing, the milestones were never recorded and the chain stops at the commit.

What stays yours

Delegating the setup does not delegate the judgement. Four things are yours:

Decision Why it cannot be delegated
The names Permanent, per team, forever. No mechanism will second-guess a bad one.
The persona prompts They are your coworkers. An agent can draft; only you know what the role is for.
Which roles exist A team's shape is a product decision about how you want to work.
When to cast Casting is the one irreversible act. Rehearse, read, then decide.

When something refuses

Your agent will hit these and should tell you plainly. If it works around one silently, that is worth knowing about:

What it means What to do
The name is already taken in this team — including by a retired worker Choose another. Names never come back.
A cast arrived with no name Names are chosen, never derived. Decide the name.
The worker is taken — someone has a live session on it Usually a real driver. Ask them, or use a different worker.
The worker is held — the name belongs to a person Not the same as taken, and it cannot be forced. Ask the holder to release it, or cast your own worker for the role.

The last two are worth understanding rather than routing around: taken and held are different states, and the difference exists because conflating them once let an agent end a colleague's mid-PR session and take their name.

After the team exists

Day-to-day work needs no setup and mostly no CLI. Your agent binds a worker session, posts to the team chat, and records milestones through Hadron's MCP tools directly: