# <Agent />

Run one provider-owned Agent session after AML resolves its prompt, system content, capabilities, and follow-up turns.
Canonical: https://agent-markup-language.com/docs/reference/primitives/agent/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<Agent />` is AML's model-session boundary. AML resolves the complete authored plan first, then asks the selected [Agent provider](https://agent-markup-language.com/docs/providers/agents/) to run one session.

```tsx
import { Agent, AmlRuntime, System } from "@aml-jsx/sdk"
import { DeterministicAgentProvider } from "@aml-jsx/sdk/testing"

const provider = new DeterministicAgentProvider({
  respond: request => ({ text: `${request.system}\n${request.prompt}` }),
})

const runtime = new AmlRuntime({ agentProvider: provider })
const result = await runtime.evaluate(
  <Agent name="authorization-review" model="reviewer" timeoutMs={30_000}>
    <System>Use only evidence supplied in the prompt.</System>
    Review the authorization change.
  </Agent>
)
```

For a live session, replace the deterministic provider with [Codex](https://agent-markup-language.com/docs/providers/agents/codex/), [GitHub Copilot](https://agent-markup-language.com/docs/providers/agents/copilot/), [OpenCode](https://agent-markup-language.com/docs/providers/agents/opencode/), or [Pi](https://agent-markup-language.com/docs/providers/agents/pi/).

## Props

| Prop          | Type                | Default                                          | Meaning                                                                                                                      |
| ------------- | ------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `children`    | `AmlRenderable`     | empty                                            | Initial prompt text plus Agent-scoped descriptors.                                                                           |
| `cwd`         | `string`            | active Sandbox cwd                               | Agent-local logical cwd. Requires an enclosing [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/); it does not create one. |
| `model`       | `string`            | provider default                                 | Provider-owned model identifier passed through by AML.                                                                       |
| `name`        | `string`            | —                                                | Optional diagnostic metadata; non-unique and never included in prompts.                                                      |
| `permissions` | partial permissions | read-write filesystem, network and shell enabled | Requested native harness controls; an active Sandbox may narrow them.                                                        |
| `provider`    | `AgentProvider`     | runtime `agentProvider`                          | Provider for this session.                                                                                                   |
| `schema`      | `AmlModelSchema`    | —                                                | Validates this Agent's result and renders it as canonical JSON text in ordinary composition.                                 |
| `system`      | `string`            | empty                                            | Fixed system text, placed after runtime system text and before child `<System />` blocks.                                    |
| `timeoutMs`   | `number`            | —                                                | Positive safe integer that bounds this provider session; caller cancellation and cleanup semantics are described below.      |

`name` is optional diagnostic metadata for relating traces and failures to the authored workflow. It must be a non-empty normalized string when supplied. Names are not unique: structural identities such as trace span IDs continue to distinguish Agents with the same name. AML includes the name in observability and diagnostics only; it never adds it to the prompt or system instructions sent to the provider.

`timeoutMs`, when present, is a positive safe integer that bounds the provider session after it acquires an Agent scheduler slot. AML derives a session signal that aborts when either this timeout expires or the enclosing evaluation is cancelled; the earliest cause wins, and nested Agents retain independent scopes. Expiry follows the same provider cancellation path as caller cancellation. AML awaits provider-owned abort and cleanup before settling the Agent, and preserves both the cancellation cause and any later cleanup failure.

## Resolution and result

AML resolves child `<Agent />` components, text, [`<Block />`](https://agent-markup-language.com/docs/reference/primitives/block/), [`<Include />`](https://agent-markup-language.com/docs/reference/primitives/include/), [`<System />`](https://agent-markup-language.com/docs/reference/primitives/system/), [`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/), [`<Tool />`](https://agent-markup-language.com/docs/reference/primitives/tool/), [`<Mcp />`](https://agent-markup-language.com/docs/reference/primitives/mcp/), and [`<FollowUp />`](https://agent-markup-language.com/docs/reference/primitives/follow-up/) descriptors before the provider session begins. Prompt and system fragments are trimmed at the session boundary; ordinary child text is otherwise concatenated without inserted separators. Skills are staged before the session, remain available for all turns, and never insert their instruction body into the prompt automatically.

The provider returns an `AgentResponse`. Normal evaluation contributes its `text` to the surrounding AML value. With `schema`, AML instead validates the structured response and renders the transformed value as canonical JSON text with deterministically ordered object keys. Transformations that produce non-JSON values, including `undefined`, reject because ordinary AML composition is a text channel.

Component-local [`evaluate()`](https://agent-markup-language.com/docs/reference/runtime/#component-local-evaluation) remains the typed collector: pass its schema as the second argument when TypeScript needs the inferred value. Do not also set the Agent `schema` prop; one Agent has one schema owner.

### Return to compose or evaluate to collect

Return a child `<Agent />` when its result should naturally occupy one authored position in the surrounding AML tree. AML resolves that child first and passes its result upward; the component that returned it does not receive the text in a local variable.

Use `await evaluate(<Agent />)` inside an active async component when later TypeScript must inspect or transform the result before deciding what AML to return:

```tsx
async function Review() {
  const finding = await evaluate(<Agent>Inspect the change.</Agent>)

  if (!finding.includes("concrete evidence")) return "No supported finding."

  return (
    <Agent>
      Synthesize the accepted finding.
      <Block tag="accepted-finding">{finding}</Block>
    </Agent>
  )
}
```

The component body runs when AML descends into `Review`, not when `<Review />` is initially authored. The awaited Agent and its cleanup finish before the body continues to the `if` statement and final return. See [Component bodies descend; results ascend](https://agent-markup-language.com/docs/concepts/#component-bodies-descend-results-ascend) for the complete mental model.

## Placement and scope

- `<Agent />` may be the root value, a child of another `<Agent />`, or a descendant of [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/) or [`<Workspace />`](https://agent-markup-language.com/docs/reference/primitives/workspace/).
- `<Agent />` capabilities belong only to their nearest containing `<Agent />`. Siblings do not inherit them.
- Child `<Agent />` results become parent input at their authored position; they are separate provider sessions.
- `cwd` does not create a Sandbox. It only narrows the cwd of an already active Sandbox session.

## Observability

An Agent trace contains one `agent.session` span, one ordered `agent.turn` span for the initial prompt and each [`<FollowUp />`](https://agent-markup-language.com/docs/reference/primitives/follow-up/), and one `agent.cleanup` span. Built-in ACP providers stream `acp.session.update` events inside the active turn and attach the final ACP stop reason and optional usage to the successful turn end.

One Agent turn is one provider `runTurn()` call. It normally maps to one ACP `session/prompt` request, but a schema-bearing final turn may contain one additional repair prompt when the Agent omits the result Tool. It must not be interpreted as one underlying model API call. See [Observability](https://agent-markup-language.com/docs/observability/#what-an-agent-trace-represents) for the lifecycle tree, content policy, and ACP limitations.

**Caution — Agent permissions are not confinement**

Native provider permissions are best-effort harness controls. Use a Sandbox provider with an appropriate isolation
model when model-controlled commands or filesystem access require an enforcing boundary.

See [Agent provider selection](https://agent-markup-language.com/docs/providers/agents/), [Sandbox compatibility](https://agent-markup-language.com/docs/compatibility/), and the [code-review workflow](https://agent-markup-language.com/docs/cookbook/code-review-workflow/) for complete compositions.