Skip to main content
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)
PurposeGives tools and context to an agentLets one agent delegate work to another agent
Integration shapeTool calls against an MCP serverJSON-RPC task execution against /a2a
Best fitDocumentation lookup, SDK guidance, coding workflowsOperational 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:
VersionHeader ValueStatus
V11.0Current and recommended
V00.3Legacy 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