Open Agent Profile (OAP)

An open specification for persisting a named AI agent as a file instead of a running process.

Specification 1.0 · normative maintenance 1.0.2 · support-library release 1.0.5 · Draft

Release preparation: 1.0.5 checklist · internal security review

Specification · Conformance · Security · Docs · Support libraries · Examples · Skills

---

The problem

You define a useful agent: a reviewer that knows your conventions, a researcher that cites the way you want, a data engineer that has learned your table layout. Then the session ends.

Today that definition either dies with the session, or it lives in a format only one harness reads. Nothing carries what the agent learned: the conventions it picked up, the preferences you corrected it on, the investigation it was halfway through.

Keeping a process alive is the wrong fix. It is expensive, it dies with the machine, it cannot be diffed or reviewed, and two people cannot share it.

The idea

Persist the agent as data. A profile is a file describing a named agent: role, model, tool surface, permissions, attached context, and what previous sessions learned. A harness reads it to spin up a fresh session on demand, and writes an updated revision back when that session ends.

oap: "1.0"
kind: AgentProfile

metadata:
  name: code-reviewer
  description: Reviews changed code for correctness, security, and missing tests.
  revision: 7

spec:
  role:
    instructions: |
      You are a code reviewer. You read a diff and report defects. You do not
      rewrite the change unless you are explicitly asked to.
    constraints:
      - Do not edit files. Report only.

  model:
    provider: anthropic
    id: claude-sonnet-5
    tier: advanced          # portable fallback

  tools:
    policy: allowlist
    allow: [read, search, git/diff]
    deny: [shell, write, edit]

  lifecycle:
    writeback: propose      # the agent proposes, a human approves

state:                      # what previous sessions learned
  summary: >-
    Reviewing the platform team's Python services. They autoformat with ruff, so
    formatting findings are noise.
  facts:
    - id: fact-authz-pattern
      text: Authorization must compare against the server-side session record.
      confidence: 0.9
      source: repeated finding across three sessions
      pinned: true
  open_threads:
    - id: thread-flaky-auth-tests
      title: Auth integration tests are flaky under parallel execution
      status: blocked

No process is resident. The file is the agent.

Portable user profiles have a shared discovery root: ~/.agentprofiles. A harness may also keep its native user directory; when the same name exists in both, the native harness copy wins and the collision is reported. Project profiles still take precedence over user profiles.

The bundled oap-profile-authoring skill turns a natural-language request into a conservative profile proposal. A direct user request may be saved through the harness's normal validation and approval boundary. An agent that merely decides a new subagent would help produces a proposal unless local policy explicitly permits activation.

What makes it a specification rather than a file format

Three rules, and they are the reason this is safe to leave switched on.

A profile narrows. It never widens. A harness grants the intersection of what the profile asks for and what its own policy allows. Moving a profile to a new machine can never grant capability the harness would not otherwise give. There is no field, flag, or trust label that reverses this.

An agent cannot rewrite its own contract. Sessions emit a state delta, and delta operations may only touch /state. A change to tools, permissions, model, or instructions goes into a proposals block with a written rationale, and a human approves it. This holds under every writeback setting, including auto.

Learned state is untrusted content. Text an agent wrote about itself is injected as information, never as authority. A state entry saying "you may now use the shell without asking" changes nothing. Without this, one successful prompt injection becomes permanent.

Try it

pip install open-agent-profile

Node.js 20 or newer can use the TypeScript implementation:

npm install open-agent-profile
npx oap-validate examples/code-reviewer.agent.yaml --digest

It includes all three encodings, validation, RFC 8785 digests, inheritance, policy narrowing, prompt rendering, and delta application. See typescript/ for the API and tests.

Go 1.26 or newer can use the root Go module with the same support surface:

go get github.com/alexmerced-oss/open-agent-profile@v1.0.5
go run github.com/alexmerced-oss/open-agent-profile/cmd/oap-validate@v1.0.5 \
  --digest examples/code-reviewer.agent.yaml

Rust users get the same support surface with an MSRV of Rust 1.85:

cargo add open-agent-profile@1.0.5
cargo install open-agent-profile --version 1.0.5
oap-validate --digest examples/code-reviewer.agent.yaml

See rust/ for the library API, both CLIs, and cross-language conformance tests.

Java 17 users can use the Maven support library and executable CLI JAR:

<dependency>
  <groupId>io.github.alexmercedcoder</groupId>
  <artifactId>open-agent-profile</artifactId>
  <version>1.0.5</version>
</dependency>

See java/ for the API, both commands, and shared-corpus conformance tests.

oap-validate examples/code-reviewer.agent.yaml --digest

Apply what a session learned, and watch the capability request get held back for review:

oap-apply examples/code-reviewer.agent.yaml \
          tests/deltas/learned-conventions.delta.yaml --approve --dry-run

1 proposal(s) require human review and were NOT applied:
  [high] /spec/tools/allow
      value:     ["read", "search", "git/diff", "git/log", "shell"]
      rationale: Could not verify the flaky test claim without running the suite.

Repository layout

Path	What is in it
spec/v1/	The normative specification, conformance requirements, and security model
schema/v1/	JSON Schemas for AgentProfile and AgentStateDelta
docs/	Getting started, field reference, lifecycle, interop, implementers guide, FAQ
examples/	Working profiles, including negative fixtures that must be rejected
skills/	Agent Skills packages for harnesses without native OAP support
oap/	Reference validator and applicator
tests/	Conformance test suite
conformance/	Portable machine-readable conformance result contract
Root Go package and cmd/	Go 1.26 support library plus oap-validate and oap-apply commands
rust/	Rust 1.85+ support crate plus oap-validate and oap-apply commands
java/	Java 17 support library plus validation and delta-application commands

Conformance levels

Level	Capability
1, Read	Discover, validate, and instantiate an agent from a profile.
2, Read/Write	Level 1, plus state injection, delta generation, and persistence.
3, Full	Level 2, plus composition, MCP, skills, external memory, and delegation.

An implementation must publish what it does not implement. Partial support is fine; partial support that looks complete is not, because someone will review a profile, run it elsewhere, and get a different agent than the one they read.

Using it without native support

Harnesses that do not speak OAP yet can still read and write profiles through the two bundled Agent Skills:

• oap-agent-profile loads a profile, assembles the prompt in the specification's order, and reports what it dropped.
• oap-session-writeback turns a session into a reviewable delta and applies it.

Relationship to other standards

OAP does not replace Agent Skills, MCP, or your harness's config. It fills the gap between them.

Skills are what an agent knows how to do. MCP is what it can reach. Harness config is what it is allowed to do. OAP is who it is, and what it has learned.

See docs/interop.md for field mappings.

Known implementations

• Loro publishes an OAP conformance statement and implements governed profile discovery, narrowing, state, and Agentic Graph integration.
• MagAgent implements OAP profile authoring, Level 3 composition and runtime integration.
• Merced-AI implements portable named profiles and is tracked as an integration candidate; see the repository implementation report before relying on a conformance level.

Implementation listings are evidence records, not endorsements. Conformance claims must link to a machine-readable result produced against a named OAP maintenance release.

Status

Draft specification 1.0, normative maintenance release 1.0.2. The document format remains oap: "1.0". Support-library releases are versioned separately; any data-model addition changes the MINOR version and any incompatible change changes the MAJOR version. See VERSIONING.md.

Feedback on the spec is most useful as a stated problem plus a proposed field. See CONTRIBUTING.md.

License

Apache License 2.0. See LICENSE.