Skip to content

interop-profile.md

Latest commit

 

History

History
143 lines (88 loc) · 8.34 KB

interop-profile.md

File metadata and controls

143 lines (88 loc) · 8.34 KB
Raw

OpenAgent interoperability profile 0.1

Purpose

This profile defines a small, testable baseline for agent runtimes that collaborate through open standards. It is a profile of A2A and MCP, not a separate protocol. If this document conflicts with either specification, the upstream specification is authoritative.

The profile has two surfaces:

Need Standard Public object
Discover an agent and exchange durable work A2A v1 Agent Card, Message, Task, Artifact
Expose tools, data, or devices to an agent runtime MCP Remote Streamable HTTP server

An A2A Task is the durable work record. An MCP tool invocation is a capability call made while work is being performed. An implementation must not make an MCP tool invocation the only durable record of cross-agent work.

Normative language

The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used as described by BCP 14 when written in capitals.

A2A v1 baseline

Discovery

  1. A conforming agent MUST publish an A2A v1 Agent Card at /.well-known/agent-card.json.
  2. The card MUST contain at least one supportedInterfaces entry with:
    • an absolute HTTPS url in production;
    • protocolBinding equal to JSONRPC;
    • a protocolVersion in the A2A 1.x series.
  3. The card MUST truthfully describe input/output media types, skills, security requirements, and optional capabilities.
  4. The card MUST NOT disclose secrets, prompts, model routing, private topology, or credentials.
  5. Clients MUST treat the card as untrusted until they have established origin trust and applied local policy. A signature can strengthen provenance but does not grant authorization.

Durable work

The minimum JSON-RPC operations are:

  • SendMessage to create or continue work;
  • GetTask to read durable status and artifacts;
  • CancelTask to request cancellation.

A sender MUST provide a unique messageId. A server SHOULD use it for idempotency according to the A2A specification. The baseline accepts text/plain; implementations MAY advertise additional standard media types.

When work cannot complete within the request, SendMessage SHOULD use configuration.returnImmediately: true and return a Task in TASK_STATE_SUBMITTED or TASK_STATE_WORKING. A server MUST make later status available through GetTask unless it advertises and implements another A2A update mechanism.

Terminal outcomes are represented as:

  • TASK_STATE_COMPLETED, with output in one or more Artifacts;
  • TASK_STATE_FAILED, with a safe failure status message;
  • TASK_STATE_CANCELED after successful cancellation;
  • TASK_STATE_REJECTED when work is intentionally not accepted.

An implementation MUST NOT report TASK_STATE_COMPLETED before the requested work has produced its final outcome. Internal queue, worker, model, or deployment states MUST remain private; they are projected into the A2A task states.

Authorization and tenancy

Authentication MUST use a standard scheme declared in the Agent Card. Authorization is evaluated per request and MUST scope access to the caller, target agent, organization/workspace, task, and operation. Possession of a valid credential does not imply access to every agent or task.

Multi-tenant services SHOULD use the A2A tenant mechanisms when applicable and MUST enforce tenant isolation even if a tenant identifier is omitted from the public URL. Servers SHOULD return indistinguishable not-found responses where revealing resource existence would cross an authorization boundary.

Optional A2A features

Streaming, push notifications, extended Agent Cards, files, additional bindings, and extensions are outside the minimum profile. They MAY be used only when truthfully advertised and implemented according to A2A v1.

MCP baseline

Modern remote MCP

The preferred MCP surface is the 2026-07-28 specification over remote Streamable HTTP.

A conforming modern endpoint MUST:

  1. expose a single authenticated HTTPS MCP endpoint in production;
  2. implement server/discover;
  3. carry protocol version, client information, and client capabilities in request _meta as defined by MCP;
  4. require the MCP-Protocol-Version and Mcp-Method headers on modern HTTP requests, plus Mcp-Name when the operation addresses a named tool, prompt, resource, or task subject;
  5. declare and implement tools if it exposes tools;
  6. return deterministic tool ordering and the required cache metadata on list responses;
  7. validate Origin, authenticate requests, authorize each exposed capability, and avoid transport-session authority.

The current MCP core is stateless. Application state uses explicit, scoped handles in ordinary tool arguments or an applicable standard extension. A hidden transport session MUST NOT be the sole authority for organizational work.

Transitional compatibility

Many deployed hosts still speak the initialization-based 2025-11-25 era. A production endpoint SHOULD be dual-era during the transition when its client population requires it. Dual-era support follows MCP's standard detection and fallback rules; it MUST NOT create a different OpenAgent-only handshake.

The included modern fixtures use server/discover. The legacy fixtures demonstrate the earlier initialize request only so implementers can test compatibility. New clients SHOULD prefer the modern era.

Tools and devices

Tools and physical devices are both capabilities from the agent's perspective. A robot, browser, terminal, sensor, calendar, or file store SHOULD be exposed through MCP tools/resources appropriate to its behavior. Device-specific safety, admission, emergency stop, rate limits, and physical authorization remain mandatory application controls.

An implementation MUST NOT infer that a successful MCP connection authorizes every tool. Tool descriptions and annotations are untrusted input, and consequential tool calls require the authority appropriate to their effects.

Runtime neutrality

The profile does not depend on a model vendor, agent framework, programming language, or hosting platform.

A Codex-, Gemini-, or Claude-style host can use OpenAgent tools when it can connect to the remote MCP endpoint. Native A2A support is not assumed. A host without A2A can participate through an adapter that:

  1. receives a standard A2A Message;
  2. creates a durable A2A Task before starting runtime execution;
  3. supplies the message content to the runtime without losing identity or authorization scope;
  4. projects progress into truthful A2A task states;
  5. writes final output to A2A Artifacts;
  6. propagates cancellation to the runtime and reports the real result.

The adapter MUST NOT expose provider prompts, model selection, private runtime identifiers, or internal scheduling in the Agent Card.

Identity and accountability

Protocol identifiers do not replace organizational identity. Implementations SHOULD maintain one persistent agent identity across work, mail, calendar, and other productivity surfaces while granting protocol credentials separately and revocably.

Every accepted task and consequential tool effect SHOULD remain attributable to the initiating identity, executing agent, applied authority, and resulting artifact or side effect. Raw model reasoning is not required and SHOULD NOT be treated as the audit record.

Conformance levels

Fixture conformance

An implementation validates the published baseline schemas and passes the local fixture suite.

Discovery conformance

An implementation passes the read-only probe for:

  • an A2A Agent Card with an A2A v1 JSON-RPC interface; and/or
  • an MCP server/discover response supporting 2026-07-28.

End-to-end conformance

End-to-end conformance additionally requires an authenticated test that proves:

  1. SendMessage delivers the input to the selected runtime;
  2. GetTask exposes durable, monotonic task status;
  3. completed output appears in an Artifact;
  4. CancelTask reaches the underlying execution and reports the actual cancellation outcome;
  5. the runtime can list and call only its authorized MCP tools;
  6. cross-tenant reads and writes fail without leaking resource existence.

The included CLI intentionally does not perform these side-effecting tests.

Versioning

Profile versions follow semantic versioning. A new protocol revision may require a new profile minor or major version. Implementations should advertise A2A and MCP versions using their standard fields, never by overloading the OpenAgent profile version.