Agent Voyager Project (AVP)

Status: Draft v0.1

AVP is an open standard for AI agents and the systems that run them. A supervisor sends a job, the agent runs it and reports back, and both sides know what to expect because both sides speak AVP.

≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈
I.   SUPERVISOR  ═════ Commission ══════▶  AGENT
what to do · which model · what's available
II.   SUPERVISOR  ◀═════ Trajectory ══════  AGENT
every model + tool call · usage · outcome
≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈

The supervisor sends a small JSON Commission (what to do, which model, what resources are available); the agent runs the work and streams back a Trajectory of events that records every model and tool call, what the run cost, and how it ended.

AVP picks a shared vocabulary instead of inventing new wire formats: CloudEvents for the event envelope, OpenTelemetry for spans and token usage, MCP for the tool-server connections a Commission carries, and Agent Skills for the skill content it carries. What AVP adds on top is small. See FOUNDATIONS.md for the full mapping.

Built and maintained by the Port of Context team.

---

Quickstart

Install and run AVP with the CLI. Currently supports on macOS and Linux.

1 · Install and run Docker

Every agent run executes in a sandbox backed by a Docker daemon. Any one of Docker Desktop, OrbStack, or colima works.

Skip this you already have Docker running.

brew install --cask docker  # or: brew install colima docker && colima start

2 · Install the avp CLI

# install uv (if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh
# installs the `avp` command
uv tool install avp-cli                            

That's it — avp is installed.

3 · Install agents

Agents are prebuilt GitHub releases

avp agent install goose
avp agent install claude-code
avp agent list

4 · Run an eval

The example eval runs on a Claude model, so set an ANTHROPIC_API_KEY. That's the example's choice, not a limitation: the commission picks the model, and goose runs other providers too, so you can target a different model with that provider's key. (The claude-code agent can instead run on a Claude subscription token from claude setup-token, exported as CLAUDE_CODE_OAUTH_TOKEN; goose calls the API directly and needs a platform key. See avp-cli/README.md for the full credential rules.)

export ANTHROPIC_API_KEY=sk-ant-...
avp init capitals --agent goose
avp eval run capitals.eval.json

The first run sets up the sandbox stack (starts the managed server, builds the agent's image); later runs reuse all of it and start in a couple of seconds.

This runs the agent on each task and prints a scorecard — every commission (one agent-config variant) scored and ranked by accuracy, pass-rate, cost per run, and turns:

avp eval · capitals-extraction · 2 items · agent=goose
 #  commission         accuracy  pass_rate    $/run  turns/run
 1  capitals-few-shot      100%       100%  $0.0164        2.0
 2  capitals-baseline      100%       100%  $0.0166        2.0

avp with no arguments shows the full command map; the complete CLI guide is in avp-cli/.

Sandboxing (always on): every avp eval / avp run executes the agent inside an OpenSandbox container — the agent's writes stay in its workspace and its network is a default-deny egress allowlist (enforcement needs kernel netfilter support; make test-docker verifies it on your host). The one prerequisite is a running Docker daemon (Docker Desktop, OrbStack, or colima); the CLI manages the rest itself. avp sandbox status shows the stack.

Vault (secrets the agent can't read): store a credential once with avp env secret create <handle> (kept in ~/.avp/secrets.toml, mode 0600), then reference it in a Commission by handle: {"vault": "<handle>"} — never the value (see commission spec §2.4). For runs that use them, the CLI starts a host-side credential-injecting broker: the sandboxed agent is pointed at the broker with only sentinels, and the broker overwrites the auth with the real value on the host before forwarding to the provider / MCP server. The secret never enters the sandbox. If the broker can't be reached from the sandbox, the run fails closed rather than expose it.

5 · Add a second agent and compare (optional)

Claude Code gives you a head-to-head. Claude Code installation

avp agent install claude-code
avp init capitals --agent goose,claude-code
avp eval run capitals.eval.json

Run an agent on a task, in an environment

Beyond evals, avp can drop an agent into a declarative environment (a container image plus a real codebase) and hand it a task. The environment is the agent's whole world; your machine isn't part of it.

# define an environment: a base image + a directory of code to work on
avp env create myproj --image python:3.12-slim --path ./my-project

# commission an agent to do a task inside it (always sandboxed)
avp run --agent goose --env myproj "Add type hints to utils.py, then run the tests"

Each run gets a fresh copy of the environment; avp run prints where the workspace landed so you can inspect what the agent changed. --path re-copies your source each run (skipping .git/node_modules/caches), so it's a tight curate-with-an-agent loop. avp env run myproj -- <cmd> runs an arbitrary command in the same environment (no agent) to see what's provisioned.

Use AVP

• Drop an agent into a sandboxed environment and give it a task: avp run --agent A --env E "<task>" builds the env's image, seeds your code into the workspace, and runs the agent in a container. Full reference in avp-cli/.
• Run an agent that emits AVP out of the box: avp-claude-agent-sdk wraps the Claude Agent SDK, which ships its own loop and tools; avp-goose is an in-process observer of Block's Goose.
• Build, run, and iterate on Commissions: avp, the local CLI, scaffolds a Commission, runs setups (Commission variants) over a dataset against the real agents, and ranks a board by accuracy / pass-rate / cost / turns.
• Consume a trajectory from another language: typed bindings generated from the same JSON Schemas the Python types use, so they cannot drift: Python, Rust, TypeScript.

Develop AVP

The core project lives under avp/ (spec plus Python/Rust/TS bindings), with agents/ and the local CLI avp-cli/ alongside. Python uses uv with its workspace root at the repo root.

git clone https://github.com/portofcontext/agent-voyager-project
cd agent-voyager-project
make sync && make check

make help lists every target. make check is the free floor (format, lint, tests, conformance, bindings drift). The paid target make conformance-check runs the v0.1 suite against real models. See CLAUDE.md to contribute and proposals/ for the spec RFC process.

What AVP defines

Three specs, each adoptable on its own:

Sub-spec	What it covers
Trajectory	The stream of events an agent emits as it runs.
Commission	The run configuration the supervisor sends at startup.
Agent Descriptor	What an agent advertises about itself before a run.

All three are data-shape specs and compose independently. The umbrella avp/core/spec/v0.1/README.md indexes them and the shared concerns.

More

• PATTERNS.md: how an application wires onto AVP, with worked examples.
• avp/core/conformance/: the language-agnostic suite every conforming implementation MUST pass, driven by the avp-conformance CLI.
• SKILL.md: a skill file for AI assistants working in this repo.

Questions or bugs: open an issue or use Discussions.