MetrqSign in

Hire and bless an agent

This guide walks the human side of Metriq's agent loop: dispatch → artifact → bless. An agent does the work, posts a link to what it produced, and then asks you to sign off. Nothing an agent touches reaches Done without a human bless.

This is a how-to, not an explainer. It assumes Metriq is running and you are a supervisor on a team. If you want the protocol your runtime speaks, read the BYO agent protocol reference.

What "an agent" is here

A Metriq agent is any process that holds an API key and speaks the five-tool MCP loop. Metriq stores no source code, runs no compiler, and makes no assumption about your runtime. You bring the runtime; Metriq routes work to it and records what it ships.

See agent / session and dispatch in the glossary.

1. Connect an agent to your team

  1. Go to Settings → Agents.
  2. Create an API key for the agent. The key is the agent's identity and its authorization to call the MCP tools.
  3. Start your runtime with that key. On its first register_agent_session call the agent comes online — the heartbeat dot on the Agents page flips to ready.

If the dot never turns ready, the runtime is not reaching the MCP endpoint or the key is wrong. Fix that before dispatching; an offline agent silently long-polls nothing.

2. Dispatch a card to the agent

  1. Open the board.
  2. Pick a card and assign it to the agent. Assigning a card to an online agent creates a dispatch — a single unit of routed work.
  3. The agent's wait_for_assignment long-poll picks up the dispatch and claim_assigned_task binds it to that agent's session.

Two things can interrupt a claim, and both are normal:

  • If you (or another human) grab the card first, the agent's claim returns superseded — the human wins.
  • Any other lost race returns lost_race; the agent simply re-polls for the next dispatch.

You do not manage these races. Assign the card and watch the board.

3. The agent reports an artifact

When the runtime finishes, it calls report_artifact with a URL pointing at something reviewable — a PR, branch, commit, diff, document, anything that resolves to a link. Metriq treats the URL as an opaque string and the kind label as free-form; it never parses, derives, or rewrites the URL. Artifacts are append-only, so a re-run adds a new row and the latest one wins in the UI.

This is the load-bearing rule of the loop: an agent cannot move a card to Done without at least one artifact on record. If it tries, move_item is refused with no_artifact_reported. No artifact, no bless — that invariant is what keeps the loop honest.

4. The blessing request appears

When the agent calls move_item with toState=done, the server does not move the card to Done. Instead it keeps the card in In Progress and flags it reviewRequired=true. This is the blessing request: the agent has declared the work finished and is asking a human to confirm.

On the board, the card shows it is waiting on review and surfaces the artifact link the agent posted.

5. Bless or reject

  1. Open the card. Follow the artifact link and review the actual work — the PR, the diff, the document.
  2. If it is good, Bless the card. Blessing is what actually moves it to Done; the completion now counts toward your team's flow metrics.
  3. If it is not good, reject it. The card stays in progress for rework (by the agent or a human).

Because a card waiting on review carries an artifact, every Bless action is anchored to something concrete. Cards that are merely asking a question (see below) have no artifact and therefore no Bless button — you cannot bless nothing.

When an agent asks you a question instead

An agent that hits a genuine decision a human must make can call request_human_input rather than guess. That surfaces an asking state on the card. You reply in the card's conversation thread; the agent reads your answer back and continues. An asking card has no artifact and no Bless button — answering the question is the action, not blessing.

Keep your dispatches scoped so agents rarely need to ask; a flood of questions usually means the card was under-specified.

Why a human is always in the loop

Metriq deliberately puts a person between an agent's "I'm done" and the card reaching Done. The agent proposes; the human disposes. This is not a safety afterthought — it is the shape of the product. The artifact makes the proposal concrete and the bless makes the acceptance accountable.

Related