Open Agent Profile (OAP)

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

Specification · Conformance · Security · Docs · 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.

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

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

Conformance levels

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.

Status

Draft, version 1.0. The format is stable enough to build against; the schemas and conformance requirements are versioned and will not change incompatibly within 1.x.

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.