OPVS Protocol
Core Concepts
OPVS uses a set of core concepts that define how agents interact. Understand these core building blocks to develop or integrate with OPVS-compliant systems.
Core Actors in OPVS Interactions
- User: The end-user, which can be a human operator or an automated service. The user initiates a request or defines a goal that requires assistance from one or more AI agents.
- OPVS Client (Client Agent): An application, service, or another AI agent that acts on behalf of the user. The client initiates communication using the OPVS protocol.
- OPVS Server (Remote Agent): An AI agent or an agentic system that exposes an HTTP endpoint implementing the OPVS protocol. It receives requests from clients, processes tasks, and returns results or status updates. From the client's perspective, the remote agent operates as an opaque (black-box) system, meaning its internal workings, memory, or tools are not exposed.
Fundamental Communication Elements
The following table describes the fundamental communication elements in OPVS:
| Element | Description | Key Purpose |
|---|---|---|
| Agent Card | A JSON document describing an agent's identity, capabilities, endpoint, skills, and authentication requirements. | Enables clients to discover agents and understand how to interact with them securely and effectively. |
| Task | A stateful unit of work created by an agent, with a unique ID and defined lifecycle. | Facilitates tracking of long-running operations and stateful multi-turn interactions and collaboration. |
| Message | A single turn of communication between a client and an agent, containing content and a role ("user" or "agent"). | Conveys instructions, content, questions, answers, or status updates that are not necessarily formal artifacts. |
| Part | The fundamental content container used within messages and artifacts. A Part holds text, attachments, a file reference URI, or inline JSON of structured data. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
| Artifact | A tangible output generated by an agent during a task (for example, a document, image, or structured data). | Houses the concrete results of an agent's work, ensuring structured and retrievable outputs. |
Interaction Mechanisms
The OPVS Protocol supports various interaction patterns to accommodate different needs for responsiveness and persistence. These mechanisms ensure that agents can exchange information efficiently and reliably, regardless of the task's complexity or duration:
- Request/Response (Polling): Clients send a request and the server responds. For long-running tasks, the client periodically polls the server for updates.
- Streaming with Server-Sent Events (SSE): Clients initiate a stream to receive real-time, incremental results or status updates from the server over an open HTTP connection.
- Push Notifications: For very long-running tasks or disconnected scenarios, the server can actively send asynchronous notifications to a client-provided webhook when significant task updates occur.
For a detailed exploration of streaming and push notifications, refer to the Streaming & Asynchronous Operations document.
Agent Cards
The Agent Card is a JSON document that serves as a digital business card for initial discovery and interaction setup. It provides essential metadata about an agent. Clients parse this information to determine if an agent is suitable for a given task, how to structure requests, and how to communicate securely. Key information includes identity, service endpoint (URI), OPVS capabilities, authentication requirements, and a list of skills.
Messages and Parts
A message represents a single turn of communication between a client and an agent. It includes a role ("user" or "agent") and a unique messageId. It contains one or more Part objects, which are granular containers for the actual content. This design allows OPVS to be modality-independent.
The Part object is a flexible container that can hold different types of content using a strict field structure. A Part must contain exactly one of the following content fields:
text: A string containing plain textual content.blob: A byte array containing binary file data (inline).uri: A string URI referencing external file content.json: A structured JSON value (e.g., object, array) for machine-readable data.
Additionally, every Part can include:
mediaType: The MIME type of the content (e.g.,"text/plain","image/png","application/json").filename: An optional name for the file or content.metadata: A key-value map for additional context.
Artifacts
An artifact represents a tangible output or a concrete result generated by a remote agent during task processing. Unlike general messages, artifacts are the actual deliverables. An artifact has a unique artifactId, a human-readable name, and consists of one or more part objects. Artifacts are closely tied to the task lifecycle and can be streamed incrementally to the client.
Agent Response: Task or Message
The agent response can be a new Task (when the agent needs to perform a long-running execution) or a Message (when the agent can respond immediately).
For more details, see Life of a Task.
Other Important Concepts
- Context (sessionId): A server-generated identifier that can be used to logically group multiple related Task objects, providing context across a series of interactions.
- Transport and Format: OPVS communication occurs over HTTPS/1. JSON-RPC 2.0 is used as the payload format for all requests and responses.
- Authentication & Authorization: OPVS relies on standard web security practices. Authentication requirements are declared in the Agent Card, and credentials (e.g., OAuth tokens, API keys) are typically passed through HTTP headers, separate from the OPVS protocol messages themselves. For more information, see Enterprise-Ready Features.
- Agent Discovery: The process by which clients find Agent Cards to learn about available OPVS Servers and their capabilities. For more information, see Agent Discovery.
- Extensions: OPVS allows agents to declare custom protocol extensions as part of their Agent Card. For more information, see Extensions & Binding Governance.