Harness Agents

Rule

Full agent harnesses are not AgentEngine providers. Use the AgentHarness
substrate in @agent-native/core/agent/harness.

Why

AgentEngine is for one model round trip beneath runAgentLoop. Harnesses like
Claude Code, Codex, Pi, Cursor, and Mastra own their own loop, workspace,
native tools, session state, compaction, approval model, and sandbox behavior.
Putting a harness under AgentEngine.stream() double-runs the loop and loses
session lifecycle semantics.

How

1. Register or resolve a harness adapter.

import {
  registerBuiltinAgentHarnesses,
  resolveAgentHarness,
} from "@agent-native/core/agent/harness";

registerBuiltinAgentHarnesses();
const harness = resolveAgentHarness("ai-sdk-harness:codex");

2. Start a turn through the run-manager bridge.

import { startAgentHarnessRun } from "@agent-native/core/agent/harness";

startAgentHarnessRun({
  runId,
  threadId,
  adapter: harness,
  input: { prompt },
  createSession: {
    sessionId,
    resumeState,
    instructions,
    sandbox,
    permissionMode: "allow-reads",
  },
  ownerEmail,
  orgId,
});

3. Persist native session state in SQL.

Use saveAgentHarnessSession, updateAgentHarnessSession, and
getLatestAgentHarnessSessionForThread. The resumeState is opaque; Agent
Native stores it but does not inspect it.

4. Surface runs through background agents.

Harness runs are projected into the shared BackgroundAgentRun shape with
createAgentHarnessBackgroundAgentController() and are available through the
existing run routes as goalId=agent-harness.

ACP Agents

Agent-Native can act as an ACP (Agent Client
Protocol) client and drive a local coding agent — Gemini CLI, Claude Code, or
any ACP-compliant agent — through this same substrate. This is scoped to local
coding: the agent is spawned as a child process speaking newline-delimited
JSON-RPC over stdio, and inherits the parent environment so it reuses the user's
local CLI login. It is not a hosted/sandboxed transport, and it is not a
chat/A2A transport.

import {
  registerBuiltinAgentHarnesses,
  resolveAgentHarness,
} from "@agent-native/core/agent/harness";

registerBuiltinAgentHarnesses();

// Built-in presets (commands overridable via the resolve config):
const gemini = resolveAgentHarness("acp:gemini");
const claude = resolveAgentHarness("acp:claude-code");

// Or any ACP agent by command:
const custom = resolveAgentHarness("acp", {
  command: "gemini",
  args: ["--experimental-acp"],
});

• The protocol transport (@zed-industries/agent-client-protocol) is an optional
  dependency loaded lazily; installPackage surfaces a clear install hint.
• The agent binary (e.g. @google/gemini-cli, @zed-industries/claude-code-acp)
  is a separate external CLI the user installs; presets launch it through npx
  by default and the command/args are overridable because agent ACP entry flags
  still evolve.
• permissionMode maps onto ACP session/request_permission using the reported
  tool-call kind: reads always run, edits run under allow-edits, everything
  risky prompts unless allow-all. Approvals surface as approval-request
  events; answer them through the harness session's approve().
• resumeState carries the ACP sessionId; resume works when the agent
  advertises the loadSession capability and degrades to a fresh session
  otherwise.
• fs/read_text_file and fs/write_text_file are served against the session
  workspace and refuse paths that escape it; terminal methods are not advertised
  (the agent uses its own shell).

Adapter Guidance

• Keep harness packages optional. Use dynamic imports in adapters and expose an
  install hint through installPackage.
• Use the AI SDK harness adapter as one implementation, not as Agent-Native's
  public abstraction.
• For bridge-backed coding harnesses, require a real sandbox/workspace provider.
  Do not run arbitrary coding agents in the host process by default.
• Pass only a narrow, intentional set of Agent-Native actions as host tools.
  Preserve defineAction auth, request context, timeouts, truncation, and
  read-only metadata.

Code Execution Sandbox

• The run-code tool executes through a pluggable SandboxAdapter
  (packages/core/src/coding-tools/sandbox/). The default
  LocalChildProcessAdapter spawns a locked-down local Node child process;
  swap it via AGENT_NATIVE_SANDBOX or registerSandboxAdapter() for a
  Docker/remote backend. An adapter only runs the already-prepared, non-secret
  module source — it never sees app secrets. See the Sandbox Adapters doc;
  agent-native add sandbox docker emits a full Docker-adapter recipe.
• Long compute exceeds the hosted ~40s run ceiling via the built-in durable
  background backend: per-call background: true on run-code (or
  AGENT_NATIVE_SANDBOX=background to queue every call) enqueues to the
  sandbox_executions table and executes out-of-band — self-dispatched to
  /_agent-native/sandbox/_process-execution on serverless, in-process on
  long-lived Node — with lease-based claiming, retries, and owner-scoped
  polling via run-code {executionId} / get-code-execution.

Sub-Agent Delegation Depth

• Sub-agent spawning is capped server-side (default depth 2) so delegation
  chains can't fan out indefinitely. Override at deploy time with
  AGENT_NATIVE_MAX_SUBAGENT_DEPTH (0 disables sub-agents; clamped to 16).
  Enforcement is ambient via evaluateSubagentDepth in
  packages/core/src/server/agent-teams.ts — independent of any tool-level
  guard. See the Agent Teams doc for the depth model.

Don't

• Don't add Claude Code, Codex, Cursor, Mastra, or Pi as an AgentEngine.
• Don't replay full Agent-Native chat history into a native harness each turn.
  Resume the harness session instead.
• Don't store resume state in application_state; it belongs in the harness
  session SQL table.
• Don't expose every app action to every harness session by default.

Related Skills

• adding-a-feature — feature parity across UI/actions/instructions/state.
• delegate-to-agent — background agents use run-manager infrastructure.
• external-agents — expose openable resources and external-agent surfaces.
• storing-data — durable SQL state and additive schema changes.