Universal Agent Protocol
Apache-2.0
Docs navigation

Introduction

UAP (Universal Agent Protocol) is an open, declarative format for defining an AI agent once — and installing it into any coding harness.

The problem

Every agent harness invents its own configuration layout. The same agent — the same instructions, the same commands, the same MCP servers — is spelled completely differently depending on the tool running it:

  • Instructions live in CLAUDE.md, or AGENTS.md, or .cursor/rules/*.mdc with frontmatter.
  • MCP servers live in .mcp.json, or a TOML config.toml, or an opencode.json key — each with different field names for the same concepts.
  • Subagents are Markdown files in one tool, TOML files in another, and per-agent directories in a third.

The result is the same integration tax the Language Server Protocol and the Model Context Protocol were created to eliminate, one level up: with N harnesses and M agents, every agent must be hand-ported N×M times. Agent definitions get locked into one tool, teams that use several harnesses maintain duplicate configs that drift apart, and there is no portable unit you can commit, share, or publish that says: this is my agent.

What UAP resolves

UAP defines a single canonical document — agent.uap.yaml — that captures everything an agent is: instructions, slash commands, subagents, skills, MCP servers, hooks, permissions, and setup. Two operations connect it to the real world:

  • pack reads a harness's on-disk layout and produces a canonical bundle.
  • unpack renders a bundle into a harness's on-disk layout — exactly where that tool actually reads it.

Adapters only ever talk to the canonical format, never to each other — converting between two harnesses is pack then unpack. N harnesses cost N adapters, not N² converters.

# capture your Claude Code project as a portable bundle
uap pack --from claude-code

# install the same agent for a teammate on Cursor
uap unpack --to cursor

# or convert directly
uap convert --from claude-code --to codex

Design principles

  • Declarative and committable. A bundle is plain files that belong in source control. Secret values are banned from bundles by the spec — only ${NAME} placeholders and declarations travel; values resolve at install time.
  • Lossless where possible, honest where not. Every adapter publishes a per-component capability table (see the matrix), and every conversion emits a fidelity report labeling each component native, emulated, or skipped. Nothing is silently dropped.
  • Deterministic. A canonical form guarantees that semantically equal documents serialize byte-identically, so diffs are meaningful and round-trips are testable — the conformance suite asserts pack(unpack(D)) ≡ D for every native component.
  • Riding the convergence. The ecosystem is already standardizing — AGENTS.md, SKILL.md folders under .agents/skills/, mcpServers JSON maps. UAP names that convergence instead of fighting it.

What UAP is not

UAP is configuration at rest, not a wire protocol. It complements rather than competes with its siblings: MCP connects a running agent to tools, ACP connects a running agent to editors — UAP defines the agent itself, portably. A UAP bundle references MCP servers; it doesn't replace them.

Next steps

  • Read the agent format — the full canonical document, component by component.
  • Check harness support — the big matrix of what's native, emulated, and planned.
  • Install the CLI and pack your first agent.