Wire Align into your agent loop

AI Assistants (MCP) covers connecting a chat client (Claude Desktop, Cursor, Copilot Chat) to Align. This page is for the other case: you are running your own agent loop - a coding agent, a conductor/worker/verifier pipeline, a CI bot - and you want it to consult the decision graph as part of its own reasoning, not just when a human asks it to.

The three tools that matter for this are already documented in detail: check_proposed_action / check_alignment (check before you act), and search / get_topic_timeline (answer a question from the graph, or get the story on a topic - see AI Assistants (MCP)). This page is about where in your loop each one belongs and what your loop should do with the result - the wiring, not the API reference.

Pick your access path first

Align exposes the same check through three equivalent surfaces, and which one your loop should use depends on what your runtime can do, not on a universal speed ranking:

Your runtime	Use	Why
Has its own API/SDK integration already	The REST API (`POST /alignment/check` and friends)	A structured call is the natural fit - no extra process, no extra round trip
Can run a shell, no direct API credentials	The installed CLI's `--json` flags (`align ask --json`, `align check --json`)	No separate client library to write
Is itself an MCP client with no shell available	MCP (`align mcp`, or the hosted connector)	First-class here - do not force a shell detour on a client that has none

Direct API credentials win when present, even if the runtime also has a shell or is MCP-native. Shell capability wins over MCP when both are present, because the CLI is the lighter default. All three call the identical backend check with identical auth and tenant resolution - this is not a "which is faster" page. The full decision table, as a tested pure function, is in align-cli's access-capability.ts and its docs page.

Where in the loop to call what

A conductor/worker loop (or any multi-step agent) touches Align at four distinct points, not on every tick:

1. Before the worker writes or changes code. Call check_alignment with the diff, phrased as the decision and its value ("set the worker pool to 12"), not the chore ("wire up a worker") - the check matches against past decisions, and a chore description gives it nothing to match against.

2. Before the loop takes an autonomous action - opening a PR, filing a ticket, posting a message, running a command with side effects. Call check_proposed_action with the drafted content and an action_type (pull_request, jira_ticket, slack_message, commit_message, or general). This is the "gate" step in a conductor/worker/verifier/gate pattern: the gate is not "did tests pass", it is "does anything already decided disagree with this".

3. When the worker needs context to decide HOW, not just whether. Before implementing something related to a topic it has not touched before, call search for a specific question ("does the webhook handler fail open or closed on a bad signature") or get_topic_timeline/get_task_context for the fuller story on an area. This is retrieval, not a gate - an empty result means nothing in the graph speaks to it, not that the behaviour is undecided.

4. After a human (or an explicitly authorised step) has acted on a flag. Call rate_conflict with the check_event_id the check returned, recording whether the flag was right. A flag nobody judges teaches the graph nothing - skip this and the check gets no better over time.

Budget seconds, not milliseconds, for steps 1 and 2. The check runs an LLM over the full conflict taxonomy; it belongs at a decision point in the loop (before a worker commits to a plan, before a gate step), never on a per-token or per-tool-call path. See Agent Alignment Layer for the current timeout and measured latency.

What the loop does with the result

Four statuses come back from steps 1 and 2, and a loop that treats any of them as "proceed" by default has reintroduced the one bug this layer exists to prevent:

Status	What it means	What your loop does
`aligned`	Consistent with, or unrelated to, existing decisions	Let the worker proceed
`conflicting`	Contradicts an active decision	Stop the worker. Surface the conflicting decision to whoever owns the loop (a human, or an escalation step) before the gate passes
`no-context`	Nothing in the graph speaks to this	Proceed, and consider this a candidate to capture once the action lands
`unknown`	The check could not run or reach a reliable verdict	Not a pass. Treat it exactly like `conflicting` - stop and surface "could not check", do not let a degraded dependency silently widen what your gate allows

A result can also carry a matched decision whose own status is conflicted - that means a later decision already overrode the one your action agrees with, so an aligned top-level status is only telling you that you agree with a stale record. Check both. The full contract, including the exact JSON shape and the unknown reason codes, is in Agent Alignment Layer.

Capturing what the loop decided: do this deliberately, not on every tick

A conductor-style loop that logs everything it does will be tempted to call capture (or align capture) automatically whenever a worker finishes a step, the way it writes to its own memory file or trust ledger. Don't wire it that way.

A merge, a passed gate, or a completed tick is not a human approving a lasting organisational decision. Align's capture is meant for decisions a person stood behind - a PR description, a Slack thread, a ticket - and feeding it unreviewed agent output turns the graph into exactly the kind of signal it is supposed to help you tell apart from noise. Capture agent-origin reasoning only from an explicit, authorised workflow step - something your loop's operator chose to wire in, not something that fires by default on every successful action.

{ "tool": "capture", "text": "We decided to cap the worker pool at 12 to stay under the DB connection limit", "source_url": "https://github.com/acme/repo/pull/421" }

If you are not sure whether a given tick's output should become a decision, don't capture it. no-context from step 2 above is a better signal for "this might be worth capturing" than any output your own loop produces - it tells you the graph currently has nothing to say about an action you are about to take, which is the case worth a human's attention.

What Align is not, inside your loop

Align is a decision seat your loop consults, not a replacement for the loop itself:

It is not your runtime, dispatcher or permission layer. It does not execute your plan steps, decide which worker runs next, or gate on anything except "does this contradict a decision" - your own conductor still owns sequencing, retries and tool permissions.
It does not substitute for human sign-off. A check_proposed_action call passing does not mean the action was approved by anyone; it means nothing in the graph currently contradicts it.
Repository context your loop already has (a CLAUDE.md, a memory/ file, a constitution) is a snapshot from whenever it was last written. Align's graph is one source your loop can check for whether that snapshot is still current - it does not replace reading the file, and the file does not replace checking the graph.

A worked loop step (runtime-neutral)

worker proposes: open a PR that changes the retry backoff from 3 to 5 attempts

conductor, before the gate:
  call check_proposed_action
    action_type: "pull_request"
    content: "<the PR title and description>"
    context: "<ticket id, or the branch name>"

  if status == "conflicting":
    stop. surface the matched decision(s) to the operator. do not open the PR.
  if status == "unknown":
    stop. surface "could not check (<reason>)". retry or escalate - do not proceed as aligned.
  if status == "aligned" or "no-context":
    let the gate open the PR.

  (separately, once a human has reviewed a conflict flag)
  call rate_conflict with the returned check_event_id

The same shape applies whether your loop speaks the REST API, the CLI's --json flags, or MCP - only the transport changes; the four steps and the status handling do not.

Next steps

Agent Alignment Layer - the full check_proposed_action / check_alignment contract, status meanings, and latency budget
AI Assistants (MCP) - the full tool list for both the CLI and hosted MCP servers
CLI - every align command and flag, including --json output

Pick your access path first​

Where in the loop to call what​

What the loop does with the result​

Capturing what the loop decided: do this deliberately, not on every tick​

What Align is not, inside your loop​

A worked loop step (runtime-neutral)​

Next steps​