open-agent-protocol 0.2.5

Open Agent Protocol — a routing layer for inter-agent task handoff

OAP — Open Agent Protocol

A lightweight routing layer for passing tasks between AI agents.

OAP defines a standard envelope format (TaskEnvelope) and a router that dispatches tasks to the right agent based on capabilities or explicit handoff instructions.

Installation

pip install open-agent-protocol

Quick start

from oap import TaskEnvelope, OAPRouter
from oap.adapters.http import HTTPAdapter

router = OAPRouter()
router.register(
    "research-agent",
    HTTPAdapter(agent_id="research-agent", base_url="http://localhost:9000"),
    capabilities=["research", "search", "find"],
)

envelope = TaskEnvelope(goal="research the best vector databases")
result = await router.route(envelope)
print(result.memory["last_result"])

CLI

# Create a new task envelope
oap init "research the best vector databases" --output task.json

# Register an HTTP agent — OAP discovers capabilities automatically from GET /
oap register research-agent http://localhost:9000
# Falls back to manual capabilities if the agent has no GET / endpoint
oap register research-agent http://localhost:9000 --capabilities "research,search,find"

# Route the envelope to the best matching agent
oap route task.json --output result.json

# Automatically follow handoffs until the task is complete
oap chain task.json --output final.json

# List all interrupted chains (saved mid-flight)
oap runs

# Resume a chain that failed or was interrupted
oap resume <envelope-id>
oap resume <envelope-id> --pipeline "agent-a,agent-b,agent-c"

# Inspect an envelope
oap inspect result.json

# Validate envelope structure
oap validate result.json

# List all registered agents
oap agents

# Check reachability of all registered agents
oap ping

# Remove an agent from the registry
oap unregister research-agent

Chaining agents

When an agent sets a handoff.next_agent on its response, oap chain automatically routes to the next agent and keeps going until the task is complete or a hop limit is reached.

# Python API
result, visited = await router.chain(envelope, max_hops=10)
print(" → ".join(visited))  # e.g. research-agent → summarise-agent

# CLI — follows handoffs automatically, prints each hop
oap chain task.json --output final.json --max-hops 5

The chain stops when:

• An agent returns a response with no handoff set, or
• max_hops is reached (default: 10)

Resuming failed chains

If a chain is interrupted (network error, agent down, hop limit hit), OAP saves progress after each hop. Resume from the last successful hop with:

oap runs                        # list all interrupted chains
oap resume <envelope-id>        # resume handoff-driven chain
oap resume <envelope-id> --pipeline "agent-a,agent-b,agent-c"  # resume a fixed pipeline
oap resume <envelope-id> --max-hops 5  # cap additional hops

Progress is stored in ~/.oap/runs/ and deleted automatically when the chain completes.

Registry

Agents are stored in ~/.oap/agents.json and persist across commands.

When an agent implements GET / returning {agent_id, capabilities, description}, registration is automatic:

oap register my-agent http://localhost:9000
# → OAP hits GET /, reads capabilities and description, saves everything

oap register my-agent http://localhost:9000 --capabilities "research,find"
# → fallback: use provided capabilities if GET / is unavailable

oap agents          # list all registered agents with description column
oap ping            # health-check all agents, auto-updates capabilities if changed
oap unregister my-agent

Agent health endpoint

Add GET / to your agent to enable self-registration and health checks:

@app.get("/")
async def info():
    return {
        "agent_id": "my-agent",
        "capabilities": ["research", "find", "search"],
        "description": "Researches topics and returns structured findings.",
        "status": "ok",
    }

Concepts

• TaskEnvelope — the standard task object passed between agents. Contains the goal, memory, steps taken, and optional constraints.
• OAPRouter — selects the best registered agent for a given envelope and invokes it.
• AgentAdapter — translates between the envelope format and an agent's native interface.
• HTTPAdapter — built-in adapter for agents that expose a POST /invoke endpoint.

License

MIT