> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clix.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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

The [Agent-to-Agent (A2A)](https://a2a-protocol.org/latest/specification/) 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`

<Warning>
  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`.
</Warning>

## 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](/mcp-server/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`.

```json theme={null}
{
  "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 |

<Warning>
  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.
</Warning>

## 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

<CardGroup cols={3}>
  <Card title="Quick Start" icon="rocket" href="/a2a/quickstart">
    Make your first v1 request and inspect the task lifecycle
  </Card>

  <Card title="Skills" icon="robot" href="/a2a/skills">
    Review the four Clix skills, payloads, and artifacts
  </Card>

  <Card title="Version Compatibility" icon="code-branch" href="/a2a/version-compatibility">
    Migrate from V0 to V1 without guessing the wire format
  </Card>
</CardGroup>