API Reference

┌─────────────────────────────────────────────────────────┐
│                     ohwow Platform                      │
│                                                         │
│  ┌──────────────┐    ┌──────────────┐   ┌────────────┐  │
│  │  A2A Server  │    │  Agent Core  │   │ A2A Client │  │
│  │              │───▶│              │──▶│            │  │
│  │  /api/a2a    │    │  Execution   │   │  Outbound  │  │
│  │  Agent Card  │    │  Engine      │   │  Requests  │  │
│  └──────┬───────┘    └──────────────┘   └─────┬──────┘  │
│         │                                     │         │
│    Auth │ Scopes                         Discovery      │
│    Rate │ Limit                          & Tasks        │
│         │                                     │         │
└─────────┼─────────────────────────────────────┼─────────┘
          │                                     │
          ▼                                     ▼
   ┌──────────────┐                    ┌──────────────┐
   │   External   │                    │   External   │
   │   Agents     │                    │   A2A Agents │
   │  (inbound)   │                    │  (outbound)  │
   └──────────────┘                    └──────────────┘

External Agent
      │
      ▼
  ┌─────────┐    ┌─────────┐    ┌──────────┐    ┌──────────┐
  │  Auth    │───▶│  Scope  │───▶│   Rate   │───▶│  Agent   │
  │  Check   │    │  Check  │    │  Limit   │    │  Execute │
  │          │    │         │    │          │    │          │
  │ Bearer   │    │ Verify  │    │ Sliding  │    │ Run the  │
  │ Token    │    │ scopes  │    │ window   │    │ task     │
  └─────────┘    └─────────┘    └──────────┘    └────┬─────┘
                                                     │
                                                     ▼
                                              ┌──────────┐
                                              │ Sanitize │
                                              │ Response │
                                              │          │
                                              │ Strip    │
                                              │ metadata │
                                              └──────────┘

Your ohwow Agent
      │
      ▼
  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
  │ Discover │───▶│  Auth    │───▶│   Send   │───▶│  Store   │
  │          │    │          │    │   Task   │    │  Result  │
  │ Fetch    │    │ Use the  │    │          │    │          │
  │ Agent    │    │ saved    │    │ JSON-RPC │    │ Summary  │
  │ Card     │    │ creds    │    │ request  │    │ only     │
  └──────────┘    └──────────┘    └──────────┘    └──────────┘

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": "tasks/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;
}

docker run -d \
  --name ohwow-connect \
  -e OHWOW_API_KEY=ohw_a2a_your_key_here \
  -e OHWOW_WORKSPACE_ID=your_workspace_id \
  -e LOCAL_AGENT_URL=http://host.docker.internal:3001 \
  -p 9090:9090 \
  ghcr.io/ohwow/connect:latest

npx ohwow-connect init

npx ohwow-connect start

# ohwow-connect configuration
workspace_id: "your_workspace_id"
api_key: "ohw_a2a_your_key_here"

# Local agents to expose via A2A
agents:
  - name: "Internal Analytics"
    description: "Runs queries against our private data warehouse"
    local_url: "http://localhost:3001/api/agent"
    skills:
      - id: "sql-query"
        name: "SQL Query"
        description: "Execute read-only SQL queries"
      - id: "report-gen"
        name: "Report Generation"
        description: "Generate formatted reports from query results"

  - name: "Document Processor"
    description: "Processes internal documents and contracts"
    local_url: "http://localhost:3002/api/agent"
    skills:
      - id: "doc-summarize"
        name: "Summarize Document"
        description: "Extract key points from a document"

# Optional settings
health_check_interval: 30  # seconds
retry_attempts: 3
log_level: "info"