Open Agent Profile (OAP)

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

Specification 1.0 · maintenance release 1.0.3 · Draft

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

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.

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.

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.

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.2
go run github.com/alexmerced-oss/open-agent-profile/cmd/oap-validate@v1.0.2 \
  --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.3
cargo install open-agent-profile --version 1.0.3
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.3</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.

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.

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.

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.

• 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.

Draft specification 1.0, maintenance release 1.0.2. The document format remains oap: "1.0". Maintenance releases fix defects without changing that string; 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.

Apache License 2.0. See LICENSE.