# Agent providers

Choose and configure AML's built-in ACP Agent providers.
Canonical: https://agent-markup-language.com/docs/providers/agents/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

**Choose your Agent — `codexAgent() · copilotAgent() · glmAgent() · opencodeAgent() · piAgent()`**

AML's built-in Agents are thin profiles over a shared Agent Client Protocol session engine. Pick the coding harness that matches your model and workflow, then keep the rest of your AML tree portable.

- **Best for:** Portable orchestration across coding-agent runtimes, Tools, MCP, Sandboxes, Workspaces, and typed results.

- **Know before using:** A provider profile does not install executables, provision credentials, or prove that a particular Sandbox image is deployable. Validate the complete Agent × Sandbox × Workspace combination.

**Five built-in profiles** **Shared lifecycle**
**Provider-dependent**

## The provider boundary

An AML Agent provider owns the model-session boundary. AML owns everything around it:

```text
AML JSX tree
  → normalize Agent request
  → resolve Workspace and Sandbox
  → acquire provider session
  → expose Tools and MCP capabilities
  → stream turns and enforce budgets
  → validate text or structured output
  → release session and resources
```

The five built-in profiles all use the shared ACP engine. They do not create a second orchestration model, own their own scheduler, or bypass AML cleanup. Their differences are the executable launch, native configuration format, permission translation, and provider-specific capability adapters.

[AML Agent Sandbox](https://agent-markup-language.com/docs/sandbox-images/) supplies the tested full and single-Agent executable baselines when
Docker, Daytona, or Modal uses its default image. Local Sandbox requires the Agent commands on the host. Credentials and
project-specific dependencies remain application-owned in every environment.

**One ACP session boundary**

Application → AML runtime → selected Sandbox and ACP process ⇄ Agent session.

ACP standardizes the session. It does not install the executable, create the Sandbox, provide credentials, or enforce isolation.

## Choose a profile

- [Codex](https://agent-markup-language.com/docs/providers/agents/codex/) — OpenAI's ACP coding-agent profile. Uses codex-acp, Codex configuration, and explicit API-key or environment credentials.

- [OpenCode](https://agent-markup-language.com/docs/providers/agents/opencode/) — OpenCode's native ACP server. Translates AML permissions into OpenCode tools and permission rules.

- [GitHub Copilot](https://agent-markup-language.com/docs/providers/agents/copilot/) — Copilot CLI's native ACP server with private invocation state and explicit runtime authentication.

- [GLM](https://agent-markup-language.com/docs/providers/agents/glm/) — Z.ai GLM Coding Plan models through the registry-listed glm-acp-agent community adapter.

- [Pi](https://agent-markup-language.com/docs/providers/agents/pi/) — Pi ACP with a generated wrapper for restricted permissions and the Pi MCP extension for Tools and MCP.

| If you need…                                          | Start with                                                                          | Why                                                                                                |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Codex-native configuration and OpenAI model workflows | [`codexAgent()`](https://agent-markup-language.com/docs/providers/agents/codex/)                                     | Writes Codex ACP configuration and maps AML filesystem mode into Codex's agent mode.               |
| GitHub Copilot plans and model access                 | [`copilotAgent()`](https://agent-markup-language.com/docs/providers/agents/copilot/)                                 | Starts `copilot --acp` with private state and maps AML permissions to Copilot deny rules.          |
| GLM Coding Plan models without a full harness         | [`glmAgent()`](https://agent-markup-language.com/docs/providers/agents/glm/)                                         | Launches the registry-listed `glm-acp-agent` adapter with an isolated session directory.           |
| OpenCode's model catalog and native tool policy       | [`opencodeAgent()`](https://agent-markup-language.com/docs/providers/agents/opencode/)                               | Starts `opencode acp --pure` and translates filesystem, shell, and network permissions.            |
| Pi's extensible tool ecosystem or Pi MCP adapter      | [`piAgent()`](https://agent-markup-language.com/docs/providers/agents/pi/)                                           | Uses Pi's generated wrapper and `pi-mcp-adapter` for AML Tools and MCP.                            |
| No credentials while designing a workflow             | [`DeterministicAgentProvider`](https://agent-markup-language.com/docs/reference/testing/#deterministicagentprovider) | Use the testing entrypoint for a local fixture; it is not one of these live coding-agent profiles. |

**Tip — Start with the harness you already operate**

There is no universal live default. Codex is the shortest tutorial path when you already have an OpenAI API key;
GitHub Copilot fits runtimes with an explicit Copilot token; OpenCode fits its model catalog and native tool policy;
Pi is the better fit when its extensible Tool and MCP path is the reason you chose the harness. Validate one live
provider before adding a remote Sandbox or durable Workspace.

## Shared prerequisites

Every built-in profile requires all of the following:

1. **An executable in the execution environment**

   The command must be present where AML calls `SandboxRuntime.spawn()`: the host for local execution, or the selected image/remote environment for a Sandbox provider. A host executable is not automatically visible inside a container or remote Sandbox.

2. **A model and credentials understood by the harness**

   AML forwards provider configuration and environment. It does not log in, select a provider account, or copy credentials into a Workspace. Configure secrets in the process environment or the provider's native secret mechanism.

3. **A compatible Workspace/Sandbox tree**

   Coding Agents normally need a Workspace-backed cwd and the ability to spawn their ACP process. A read-only request can still fail to launch on a Sandbox that rejects `spawn()` for read-only access.

4. **Provider-specific runtime tools**

   Images may need a shell, filesystem utilities, the native harness, an ACP adapter, and MCP adapter dependencies. The generic compatibility handshake checks the shape of the Sandbox runtime; it does not check credentials, image contents, network policy, or model availability.

## Portable Agent shape

Keep the provider at the edge of the tree so the workflow remains portable:

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

const provider = opencodeAgent({
  model: process.env.AML_MODEL,
})

const runtime = new AmlRuntime({ agentProvider: provider })
const answer = await runtime.evaluate(
  <Agent system="Be concise and cite the files you inspected.">
    Review the current change and report actionable findings.
  </Agent>
)
```

[`<Agent />`](https://agent-markup-language.com/docs/reference/primitives/agent/) also accepts a provider directly, which is useful when different specialists in one evaluation use different profiles:

```tsx
import { Agent, AmlRuntime, codexAgent, opencodeAgent } from "@aml-jsx/sdk"

const codex = codexAgent({ model: "gpt-5.6-luna", reasoningEffort: "low" })
const opencode = opencodeAgent({ model: "opencode-go/deepseek-v4-flash" })

const answer = await new AmlRuntime().evaluate(
  <Agent name="review-coordinator" provider={codex} system="Synthesize the two specialist reviews.">
    <Agent name="authorization-specialist" provider={codex}>
      Inspect authorization changes.
    </Agent>
    <Agent name="operations-specialist" provider={opencode}>
      Inspect operational changes.
    </Agent>
  </Agent>
)
```

For independent specialist branches whose text flows directly into the tree, use
[`<Parallel>`](https://agent-markup-language.com/docs/reference/primitives/parallel/). Use explicit `Promise.all([evaluate(...)])` when component code
needs named or typed results. AML's scheduler and budgets remain in charge in both forms.

## Cross-provider capability matrix

| Capability                 | Codex                          | GitHub Copilot                       | GLM                                   | OpenCode                                             | Pi                                        |
| -------------------------- | ------------------------------ | ------------------------------------ | ------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| ACP command                | `codex-acp`                    | `copilot --acp`                      | `glm-acp-agent`                       | `opencode acp --pure`                                | `pi-acp`                                  |
| Native command option      | `codexPathOverride`            | `command` selects Copilot launcher   | None; the adapter is self-contained   | `command` selects OpenCode launcher                  | `piCommand` selects native Pi command     |
| Provider model fallback    | `model`                        | `model`, defaulting to `auto`        | `model` as `ACP_GLM_MODEL`            | `model`, then `config.model`                         | `model`                                   |
| Agent-level model override | Yes                            | Yes                                  | Yes                                   | Yes                                                  | Yes                                       |
| System instruction mapping | Codex `developer_instructions` | First-turn text prefix               | First-turn literal `<SYSTEM>` prelude | First-turn literal `<SYSTEM>` prelude                | First-turn text prefix                    |
| Project instruction files  | Loads `AGENTS.md` hierarchy    | Disabled by the AML launch profile   | Loads `AGENTS.md` itself              | Loads project `AGENTS.md` or `CLAUDE.md`             | Loads project `AGENTS.md` or `CLAUDE.md`  |
| Filesystem mapping         | Codex `INITIAL_AGENT_MODE`     | Write deny rule and tool exclusion   | Enclosing Sandbox                     | `edit`/`write` tool and permission rules             | Generated wrapper `--tools` list          |
| Shell mapping              | Enclosing Sandbox              | Shell deny rule and tool exclusion   | Enclosing Sandbox                     | OpenCode `bash` tool and permission                  | Generated wrapper `bash` tool             |
| Network mapping            | Enclosing Sandbox              | URL deny rule and web tool exclusion | Enclosing Sandbox                     | OpenCode `webfetch`/`websearch` tools and permission | Enclosing Sandbox/network policy          |
| AML JavaScript Tools       | Shared ACP MCP bridge          | Shared ACP MCP bridge                | Shared ACP MCP bridge                 | Shared ACP MCP bridge                                | Pi MCP extension and generated wrapper    |
| Authored MCP               | Shared ACP session             | Shared ACP session                   | Shared ACP session                    | Shared ACP session                                   | `agent/mcp.json` through `pi-mcp-adapter` |
| Agent Skills discovery     | Native staged `CODEX_HOME`     | Metadata-only system fallback        | Metadata-only system fallback         | Native configured `skills.paths`                     | Metadata-only system fallback             |
| Structured output          | Shared ACP path                | Shared ACP path                      | Shared ACP path                       | Shared ACP path                                      | `aml_submit_result` MCP call              |
| Per-session state          | Codex home/config/sqlite/logs  | Private `COPILOT_HOME`               | Adapter `ACP_GLM_SESSION_DIR`         | OpenCode DB and XDG directories                      | Pi HOME, agent, and session directories   |

The matrix describes the profile translation, not a guarantee that every provider can run in every Sandbox. Consult the Sandbox provider page for `exec`/`spawn` behavior and the individual Agent page for launch prerequisites.

## Capabilities are layered

The contracts below belong to AML, not to a particular coding harness. Individual provider pages focus on executable
setup, authentication, native configuration, permission translation, state isolation, and provider-specific adapters.

### Tools

AML JavaScript Tools execute in the application process. They are validated by AML, then exposed to ACP profiles through the shared MCP bridge or provider-native extension. A Tool is not automatically sandboxed just because its owning `<Agent />` is inside `<Sandbox />`. Use the [JavaScript Tool guide](https://agent-markup-language.com/docs/cookbook/tools/) for the complete definition and security model.

### MCP

MCP server identity, allowlists, transport configuration, and lifecycle belong to AML's normalized Agent request. The provider maps that request into its ACP or native configuration. Executable stdio servers must exist in the provider environment; remote servers still require URL, headers, network access, and credential configuration. Use the [MCP guide](https://agent-markup-language.com/docs/cookbook/mcp/) for transport examples and failure handling.

### Skills

[`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/) stages a complete local Agent Skills package and passes concrete paths in the normalized Agent request. Codex maps the shared staging root to `CODEX_HOME`; OpenCode appends each package directory to configured `skills.paths`. Copilot, GLM, and Pi receive metadata-only system guidance naming each Skill, its activation description, and the concrete `SKILL.md` path. No provider receives the Skill body as automatic prompt text, and AML never fetches or installs remote packages.

### Structured output

`evaluate(value, schema)` asks for one typed structured `<Agent />` result; `<Agent schema={schema}>` validates a nested Agent and contributes canonical JSON text to ordinary composition. Built-in ACP profiles submit candidates through the invocation-owned `aml_submit_result` MCP tool. AML validates each candidate immediately with the supplied Standard Schema: an invalid candidate is returned to the Agent as a tool error, the first valid candidate is accepted, and later submissions are ignored. If the final authored turn ends without an accepted candidate, AML sends one repair prompt that repeats the provider-specific Tool instruction and complete JSON Schema. A second omission rejects the evaluation.

With tracing enabled, AML emits `agent.output` for every submission with its call number and `invalid`, `accepted`, or `ignored` status. Payloads are excluded from metadata-only traces and included only for a sink that explicitly enables content capture. See the [structured-output cookbook](https://agent-markup-language.com/docs/cookbook/structured-output/) for the complete pattern.

### Follow-up turns

[`<FollowUp />`](https://agent-markup-language.com/docs/reference/primitives/follow-up/) stays in the same provider session. Tools and MCP capabilities remain fixed for the session; later turns cannot widen access. A failure stops subsequent turns and rejects the evaluation.

The shared engine exposes each real turn as an `agent.turn` span and forwards every ACP notification as one `acp.session.update` event without translating ACP variants into AML-specific Tool, message, or plan schemas. Read [Agent and ACP observability](https://agent-markup-language.com/docs/observability/#the-acp-boundary) for the portable contract and its limits.

## Security checklist

**Trust the process boundary**

ACP permission mappings are provider policy. They are not a substitute for a Sandbox, container policy, network
egress policy, or secret manager.

**Keep secrets out of Workspaces**

Pass credentials through provider-native environment configuration. Do not write them into files that Agents, Tools,
revisions, or remote transfers can access.

**Audit host-side Tools**

JavaScript Tools run in the host process unless your Tool implementation delegates elsewhere. Allowlist inputs and
avoid exposing arbitrary filesystem or process primitives.

**Treat images as runtime contracts**

A remote image must contain the ACP command, native Agent, shell, utilities, and credentials/configuration expected
by the selected profile.

## Debugging a failed launch

1. Run the exact configured `command` and `args` in the same environment as AML.
2. Confirm that a Workspace is materialized and that the effective Sandbox cwd exists.
3. Check whether the Sandbox's `access` permits the `spawn()` needed by an ACP Agent.
4. Verify provider credentials and model identifiers independently of AML.
5. Enable AML tracing without content capture while diagnosing lifecycle and cleanup.
6. Inspect the provider-specific page for session state, wrapper files, permission mapping, and structured-output behavior.

## Provider source and protocol references

- [Agent Client Protocol](https://agentclientprotocol.com/) — Protocol concepts, transports, and provider expectations.

- [Codex profile](https://agent-markup-language.com/docs/providers/agents/codex/) — Codex executable, credentials, permissions, and structured output.

- [OpenCode profile](https://agent-markup-language.com/docs/providers/agents/opencode/) — OpenCode ACP launch and native capability mapping.

- [GitHub Copilot profile](https://agent-markup-language.com/docs/providers/agents/copilot/) — Copilot CLI authentication, private state, permissions, and native ACP launch.

- [GLM profile](https://agent-markup-language.com/docs/providers/agents/glm/) — GLM Coding Plan credentials, adapter tools, and session isolation.

- [Pi profile](https://agent-markup-language.com/docs/providers/agents/pi/) — Pi wrapper, MCP adapter, and session isolation.

- [AML provider source](https://github.com/we-are-singular/aml/tree/main/providers/agents) — Source of truth for built-in provider profiles.

- [AML provider tests](https://github.com/we-are-singular/aml/tree/main/providers/agents) — Launch-shape, permission, and live integration evidence.

## Core Agent documentation

- [JavaScript Tools](https://agent-markup-language.com/docs/cookbook/tools/) — Define, scope, validate, and operate an application-owned Tool.

- [Model Context Protocol](https://agent-markup-language.com/docs/cookbook/mcp/) — Declare MCP servers, transports, allowlists, and runtime requirements.

- [Runtime configuration](https://agent-markup-language.com/docs/runtime/) — Configure limits, cancellation, lifecycle events, tracing, and cleanup.

- [Agent component reference](https://agent-markup-language.com/docs/reference/primitives/agent/) — Review Agent props, resolution, capability scope, and result behavior.