Overview

Use the Agent-to-Agent (A2A) protocol to let external agents execute Clix skills through JSON-RPC.

The Agent-to-Agent (A2A) protocol lets one agent discover another agent, negotiate capabilities, and exchange task-oriented JSON-RPC messages. Clix exposes A2A so your agent can create users, track events, send push notifications, and trigger campaigns through a single remote-agent interface.

What Clix Supports

Clix currently documents and supports this A2A surface:

• GET /.well-known/agent-card.json for public agent discovery
• POST /a2a for JSON-RPC 2.0 method calls
• JSONRPC as the only advertised protocol binding
• X-API-Key with a Secret API Key (clix_sk_...) for authenticated calls
• Four built-in skills: create-user, track-event, send-push-notification, trigger-campaign

Clix does not expose separate A2A HTTP+JSON or gRPC endpoints. Use the supportedInterfaces entry in the Agent Card and send JSON-RPC requests to /a2a.

A2A vs MCP

Clix supports two complementary protocols for AI integrations:

	MCP (Model Context Protocol)	A2A (Agent-to-Agent)
Purpose	Gives tools and context to an agent	Lets one agent delegate work to another agent
Integration shape	Tool calls against an MCP server	JSON-RPC task execution against /a2a
Best fit	Documentation lookup, SDK guidance, coding workflows	Operational actions such as user creation, event tracking, push delivery, and campaign triggers

Use Clix MCP Server when your assistant needs context. Use A2A when your agent needs to execute work inside Clix.

Request Flow

1. Client Agent  ->  GET /.well-known/agent-card.json  ->  Discover public capabilities
2. Client Agent  ->  POST /a2a GetExtendedAgentCard    ->  Read authenticated card
3. Client Agent  ->  POST /a2a SendMessage             ->  Execute a task
4. Client Agent  ->  POST /a2a GetTask/ListTasks       ->  Read task state or artifacts
5. Client Agent  ->  POST /a2a SendStreamingMessage    ->  Receive SSE status updates

Agent Card Shape

With A2A-Version: 1.0, the public Agent Card uses v1 field names such as supportedInterfaces, securitySchemes, and securityRequirements.

{
  "name": "Clix Agent",
  "description": "AI Agent for Clix - Send push notifications, manage campaigns, and track user events",
  "supportedInterfaces": [
    {
      "url": "https://api.clix.so/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "name": "X-API-Key",
        "location": "header",
        "description": "Secret API key for A2A authentication"
      }
    }
  },
  "securityRequirements": [
    {
      "schemes": {
        "apiKey": []
      }
    }
  ]
}

The authenticated GetExtendedAgentCard method returns the same v1 schema. In the current Clix implementation, the main difference is a project-aware description string.

Core Concepts

Task

A task is the unit of execution in Clix A2A. Tasks are created from SendMessage or SendStreamingMessage and tracked with GetTask or ListTasks.

Current v1 task states serialize to protocol values:

submitted -> working -> completed
                      -> failed
                      -> canceled
                      -> rejected
                      -> input-required
                      -> auth-required

Message

A message is a communication turn. For client requests, use role: "user". Agent-authored messages use role: "agent".

Part

A message part can contain:

• text for natural-language content
• data for structured skill payloads

For production integrations, prefer explicit data.skill payloads over natural-language-only requests.

Artifact

Artifacts hold task output. Each built-in Clix skill writes a named artifact such as user-result, event-result, delivery-results, or trigger-result.

Protocol Versions

Clix supports two protocol versions:

Version	Header Value	Status
V1	1.0	Current and recommended
V0	0.3	Legacy compatibility mode

If you omit A2A-Version, Clix defaults to V0 behavior. Always send A2A-Version: 1.0 when you want the v1 field names and method names documented here.

Authentication Model

Authenticated /a2a calls require:

• X-API-Key: clix_sk_...
• Content-Type: application/json

To use the documented v1 field names and method names, also send A2A-Version: 1.0.

Public API keys are rejected for /a2a. The project is resolved directly from the Secret API Key, so you do not send a separate project header.

Next Steps

Quick Start

Make your first v1 request and inspect the task lifecycle

Skills

Review the four Clix skills, payloads, and artifacts

Version Compatibility

Migrate from V0 to V1 without guessing the wire format