Agent Blueprints Protocols

Protocols define the rules of communication between Orbit agents and the platform.
While Metadata describes what an agent is and Schema defines what it does,
Protocols ensure that agents interact in a consistent, secure, and interoperable way.

Why Protocols Matter

Security — enforce authentication, HMAC signing, and rate limits.
Consistency — all agents expose a predictable /invoke and /health contract.
Interoperability — enables agent-to-agent (A2A) communication within Orbit.
Composability — makes it possible to chain agents, tools, and Orbit Flow components.

Core Protocol Requirements

All Orbit-compliant agents must support the following:

1. Health Check

Path: /health
Method: GET
Purpose: Verify the agent is alive and ready.
Expected Response:

{
  "status": "ok",
  "uptime": 12345,
  "version": "0.1.0"
}

2. Invocation Contract

Path: /invoke
Method: POST
Purpose: Standard entry point for executing tools.
Request Body:

{
  "tool": "invoices.list",
  "input": {
    "status": "pending",
    "limit": 10
  },
  "context": {
    "userId": "abc123",
    "sessionId": "xyz789"
  }
}

Response Example:

{
  "success": true,
  "output": [
    {
      "invoiceId": "inv-001",
      "amount": 150.0,
      "status": "pending"
    }
  ]
}

3. Authentication & Compliance

Defined inside the agent’s meta.compliance and meta.security sections:

Authentication Required
- Example: OAuth2, API keys, or Orbit HMAC headers.
HMAC Signing
- Ensures payload integrity between Orbit and the agent.
Rate Limits
- Specified in metadata (perMinute, perHour).

4. Error Handling

Agents must return errors in a consistent JSON shape:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Status must be one of pending, paid, overdue."
  }
}

Protocol Extensions

Beyond the core requirements, Orbit Protocol supports:

Agent-to-Agent (A2A) Protocol
- Agents can call other agents securely using Orbit’s message bus.
Streaming Responses
- Agents may stream token-by-token responses if streaming: true in metadata.
Custom Endpoints
- Additional routes may be exposed (e.g., /train, /sync), but must be documented in metadata.

Best Practices

Always implement /health and /invoke.
Validate input against inputSchema before execution.
Include meaningful error codes (not just messages).
Log securely — avoid sensitive data leaks.
Version your protocols (meta.version) when contracts change.
Keep security defaults strict (auth required, HMAC on).

Relationship to Blueprints

Metadata → Who the agent is.
Schema → What the agent can do.
Protocol → How the agent communicates.
Together, these three layers make Orbit agents portable, interoperable, and secure.

Agent Metadata — overall structure of ai-tools.json
Agent Registry — where agents are registered
Declarative Schema — how outputs become UI

On this page