# Custom Agents
A custom agent is a program that runs **inside the VM** to drive a coding agent. AgentOS spawns it when you call `openSession({ sessionId, agent })` and talks to it over the Agent Client Protocol. You ship it as a software package, exactly like the built-in agents.
## Agent Client Protocol (ACP)
agentOS speaks the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) to every agent: JSON-RPC over stdio. The agent reads protocol messages on **stdin** and writes them on **stdout**, so stdout is reserved for ACP and **stderr is used for logs**. Your program only needs to speak ACP; how it runs the underlying model is up to you. See the [ACP documentation](https://agentclientprotocol.com) for the full protocol.
## Two ways to build an agent
There are two shapes, depending on whether the agent runs in the ACP process or in its own.
### Single process (embedded)
The ACP adapter **embeds the agent SDK** and runs it in the same process. One process inside the VM, lower memory footprint.
For example, an adapter to run **OpenCode**, which speaks ACP natively. One package is both the ACP process and the agent, so there's no separate adapter and nothing else is spawned.
examples/custom/opencode.ts:
```ts
import opencode from "@agentos-software/opencode";
// OpenCode *is* the ACP process: it speaks ACP on stdio itself, so there is no
// separate adapter to spawn the agent. The published @agentos-software/opencode
// descriptor already encodes the right entrypoint and env, so use it as-is.
export default opencode;
```
### ACP adapter (separate agent)
The ACP adapter is a thin **bridge** that spawns the real agent as its **own process** (a CLI or SDK) and translates between it and ACP. Full agent feature set, higher memory.
For example, an adapter to run **Pi**: the `pi` CLI doesn't speak ACP, so `pi-acp` speaks ACP and spawns the CLI as a separate process. The packaged agent bundles both — its `agentos-package.json` names `pi-acp` as the `acpEntrypoint` and points it at the `pi` CLI via `agent.env`.
examples/custom/pi-cli.ts:
```ts
import { defineSoftware } from "@rivet-dev/agentos";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
const packagePath = resolve(dirname(fileURLToPath(import.meta.url)), "..");
// Example: a pi-acp adapter that runs the Pi CLI.
// The agent block lives in the package's agentos-package.json, generated by `agentos-toolchain pack --agent`.
export default defineSoftware({ packagePath });
```
## Use your agent
Register the package on the server with `software`. Sessions are then created from the client by `id`, exactly like any built-in agent.
```ts title="server.ts"
import { agentOS, setup, defineSoftware } from "@rivet-dev/agentos";
const myAgent = defineSoftware({
packagePath, // the packed agent .aospkg; its embedded manifest carries the agent block
});
const vm = agentOS({ software: [myAgent] });
export const registry = setup({ use: { vm } });
registry.start();
```
See [Sessions](/agentos/docs/sessions) for creating and driving sessions. Package your adapter with `agentos-toolchain pack --agent my-agent-acp` so its dependencies are bundled into the self-contained package directory and the `agent` block (naming the `bin/` ACP entrypoint) is written into the package's `agentos-package.json`, rather than shipping it as a loose file.
All built-in agents are defined exactly this way. Browse them for reference on [GitHub](https://github.com/rivet-dev/agentos/tree/main/software).
## Read more
- [Defining software packages](/agentos/docs/custom-software/definition): the full descriptor reference, including the `agentos-package.json` schema and every `agent` field (`acpEntrypoint`, `env`, `launchArgs`, `snapshot`).
- [Building binaries](/agentos/docs/custom-software/building-wasm): compile WASM command binaries and use the registry.
## Debugging
When a custom agent exits mid-turn or a tool call fails, capture the agent's stderr with the `onAgentStderr` hook on `AgentOs.create()`. The agent uses stdout for ACP, so stderr carries its logs and crash output. See [Debugging](/agentos/docs/debugging) for that hook and the runtime (sidecar) logs.