API Reference

interface A2AAgentCard {
  name: string;              // Display name
  description: string;       // What this agent system does
  url: string;               // A2A endpoint URL
  version: string;           // Protocol version (e.g. "0.3")
  capabilities: {
    streaming: boolean;             // Supports SSE streaming
    pushNotifications: boolean;     // Supports push notifications
    stateTransitionHistory: boolean; // Returns task history
  };
  authentication: {
    schemes: string[];       // e.g. ["bearer"]
    credentials?: string;    // How to get credentials
  };
  defaultInputModes: string[];  // e.g. ["text"]
  defaultOutputModes: string[]; // e.g. ["text"]
  skills: A2ASkill[];          // List of agent capabilities
}

interface A2ASkill {
  id: string;           // Unique identifier (e.g. "content-writing")
  name: string;         // Human-readable name
  description: string;  // What this skill does
  tags?: string[];      // Searchable tags
  examples?: string[];  // Example prompts
  inputModes?: string[];  // Override default input modes
  outputModes?: string[]; // Override default output modes
}

POST /api/a2a HTTP/1.1
Content-Type: application/json
Authorization: Bearer ohw_a2a_your_key_here

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        { "type": "text", "text": "Your task description here" }
      ]
    },
    "sessionId": "optional-session-id"
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "task_abc123",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{ "type": "text", "text": "Here are the results..." }]
      }
    },
    "artifacts": []
  }
}

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tasks/get",
  "params": {
    "id": "task_abc123",
    "historyLength": 10
  }
}

interface A2ATask {
  id: string;
  sessionId?: string;
  status: {
    state: 'submitted' | 'working' | 'input-required'
         | 'completed' | 'canceled' | 'failed';
    message?: A2AMessage;
    timestamp?: string;
  };
  artifacts?: A2AArtifact[];
  history?: A2AMessage[];
  metadata?: Record<string, unknown>;
}

interface A2AMessage {
  role: 'user' | 'agent';
  parts: A2APart[];
  metadata?: Record<string, unknown>;
}

type A2APart = A2ATextPart | A2AFilePart | A2ADataPart;

interface A2ATextPart {
  type: 'text';
  text: string;
}

interface A2AFilePart {
  type: 'file';
  file: {
    name?: string;
    mimeType?: string;
    bytes?: string;  // base64
    uri?: string;
  };
}

interface A2ADataPart {
  type: 'data';
  data: Record<string, unknown>;
}

interface A2AArtifact {
  name?: string;
  description?: string;
  parts: A2APart[];
  index: number;
  append?: boolean;
  lastChunk?: boolean;
}