Coding agents

Why put a coding agent in a document?

Use a coding agent when a workflow has both predictable steps and a part that needs judgment. A single document keeps the instructions, agent result, and later processing together. You can run a repository review, planning task, maintenance check, migration preparation, or documentation update the same way each time.

Capture the agent's result and use it in a later document stage. Keep unattended work bounded by choosing the working directory, permission policy, and time limit before it starts.

When to use it

Agent documents work well when you want to:

• Review a repository and turn the findings into a checklist.
• Investigate a failure, then pass the diagnosis to a later stage.
• Maintain documentation from source changes.
• Ask several related questions in one working session.
• Add agent judgment to an otherwise deterministic workflow.

Use normal executable components for deterministic shell and process work. Use the stateless sampling API when no coding-agent session or repository interaction is needed. For a one-off conversation, use an interactive agent directly instead of creating a repeatable workflow.

A complete first workflow

This document asks for a review, captures it, asks a follow-up in the same conversation, and presents both results. Save it asreview.md in the repository to review.

<Agent>
  <Session name="review">
    <Prompt text="Review the current repository. List the highest-risk changes as a checklist." as="review" />
    <Prompt text="Turn that review into the next three actions." as="actions" />
  </Session>
</Agent>

## Review checklist

{review}

## Next actions

{actions}

<Agent> chooses the coding agent. The first<Prompt> captures its reply as reviewinstead of placing it immediately in the output. The two headings later in the document show the captured review and actions. Without aname prop, <Agent> uses the selected default; set name only when this document needs to override that choice.

Run the workflow with an agent your ACPX setup can run:

xmd run review.md --default-agent codex

The rendered document contains the review checklist followed by the next actions. If you omit as, a prompt reply appears at the prompt's position instead.

Continue the same task

The named <Session name="review"> in the example keeps the follow-up connected to the review. Use a session when a later prompt should retain the context of earlier work, such as asking an agent to turn findings into a plan. Use different session names for separate conversations in the same document.

Run it safely

Start from the default, --approve-reads. It allows read and search requests, asks about other requests in an interactive terminal, and denies those other requests when no interactive terminal is available. This is the safest common choice for reviews and investigations.

• Where may it work? Run xmd from the repository or directory the agent should use. That working directory determines where its session starts or resumes.
• What may it do? Choose --approve-reads,--approve-all, or --deny-all. The flags are mutually exclusive.
• How long may it wait? Prompts have a two-minute default limit. Use --timeout 90 for a shared 90-second limit for each operation without its own timeout, or set a prompt-specific timeout when one request needs a different limit.

Give a single prompt a broader or interactive policy only when that work requires it. These wrappers apply only to their contents:

<ApproveAll>
  <Prompt text="Apply the approved migration." />
</ApproveAll>

<AskPermission>
  <Prompt text="Make the proposed edit." />
</AskPermission>

<ApproveAll> chooses an available allow option;<AskPermission> asks in an interactive terminal and otherwise denies. No JavaScript eval block is needed to use either.

Reference

xmd run uses ACPX by default. Agent defaults become more specific in this order: ACPX default, DEFAULT_AGENT_NAME,--default-agent, an enclosing<AgentProvider defaultAgent="…">, then an explicit<Agent> or <Prompt agent="…" />. Use --agent-provider acpx to state the current provider explicitly.

A session, agent, or timeout prop on <Prompt> overrides the enclosing choice for that one request. When the document finishes, active work is cancelled and the agent resources close before the command completes.

Unknown agent provider "…" means the provider flag is not registered. agent "…" is unavailable means the selected agent could not be checked; verify its name, installation, and ACPX configuration. For a timeout or denial, first check the working directory, permission choice, and limit.

Test the workflow without a model

Use the bundled test agent to verify prompts, sessions, captures, and failure handling with controlled replies instead of a real model. Thedeterministic test-agent guide starts with the normal xmd test workflow and includes an advanced ACPX walkthrough for client integration work.