Agent providers

Built-in Agent providers

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:

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 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 session boundaryAML runs the Agent where the files and commands are

Applicationauthors tree · sets policy

→

AML runtimescopes · budgets · cleanup

→

Selected SandboxACP processcwd · tools · native harness

⇄

Agent sessionturns · updates · result

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

Choose a profile

CodexOpenAI's ACP coding-agent profile. Uses codex-acp, Codex configuration, and explicit API-key or environment credentials.

OpenCodeOpenCode's native ACP server. Translates AML permissions into OpenCode tools and permission rules.

GitHub CopilotCopilot CLI's native ACP server with private invocation state and explicit runtime authentication.

GLMZ.ai GLM Coding Plan models through the registry-listed glm-acp-agent community adapter.

PiPi 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()	Writes Codex ACP configuration and maps AML filesystem mode into Codex’s agent mode.
GitHub Copilot plans and model access	copilotAgent()	Starts copilot --acp with private state and maps AML permissions to Copilot deny rules.
GLM Coding Plan models without a full harness	glmAgent()	Launches the registry-listed glm-acp-agent adapter with an isolated session directory.
OpenCode’s model catalog and native tool policy	opencodeAgent()	Starts opencode acp --pure and translates filesystem, shell, and network permissions.
Pi’s extensible tool ecosystem or Pi MCP adapter	piAgent()	Uses Pi’s generated wrapper and pi-mcp-adapter for AML Tools and MCP.
No credentials while designing a workflow	DeterministicAgentProvider	Use the testing entrypoint for a local fixture; it is not one of these live coding-agent profiles.

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:

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 /> also accepts a provider directly, which is useful when different specialists in one evaluation use different profiles:

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>. 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 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 for transport examples and failure handling.

Skills

<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 for the complete pattern.

Follow-up turns

<FollowUp /> 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 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 ProtocolProtocol concepts, transports, and provider expectations.

Codex profileCodex executable, credentials, permissions, and structured output.

OpenCode profileOpenCode ACP launch and native capability mapping.

GitHub Copilot profileCopilot CLI authentication, private state, permissions, and native ACP launch.

GLM profileGLM Coding Plan credentials, adapter tools, and session isolation.

Pi profilePi wrapper, MCP adapter, and session isolation.

AML provider sourceSource of truth for built-in provider profiles.

AML provider testsLaunch-shape, permission, and live integration evidence.

Core Agent documentation

JavaScript ToolsDefine, scope, validate, and operate an application-owned Tool.

Model Context ProtocolDeclare MCP servers, transports, allowlists, and runtime requirements.

Runtime configurationConfigure limits, cancellation, lifecycle events, tracing, and cleanup.

Agent component referenceReview Agent props, resolution, capability scope, and result behavior.