CKB A2A Integration Guide

CKB exposes its 80+ code intelligence tools as an A2A (Agent-to-Agent) protocol server, enabling any A2A-compatible agent to discover, query, and orchestrate CKB's capabilities without custom integration.

Looking for MCP integration? See MCP-Integration for Claude Code, Cursor, Windsurf, and other MCP-based tools. A2A is for agent-to-agent communication — when you want one AI agent to call CKB as a remote agent over HTTP.

Quick Start

# Install CKB
npm install -g @tastehub/ckb

# Initialize your repository
ckb init && ckb index

# Start the A2A server
ckb a2a --port 8081

The agent card is published at:

http://localhost:8081/.well-known/agent-card.json

What is A2A?

A2A (Agent-to-Agent) is an open protocol under the Linux Foundation that enables AI agents to communicate with each other. Unlike MCP (which connects an AI assistant to tools via stdio), A2A connects agents over HTTP using standard JSON-RPC and REST bindings.

	MCP	A2A
Transport	stdio (local)	HTTP (local or remote)
Discovery	Manual config	Agent card at well-known URL
Use case	IDE ↔ tool server	Agent ↔ agent orchestration
Protocol	JSON-RPC over stdio	JSON-RPC + HTTP+JSON over HTTP
Streaming	Notifications	Server-Sent Events (SSE)
State	Stateless tools	Stateful tasks with lifecycle

When to use A2A instead of MCP:

You're building a multi-agent system where one agent orchestrates CKB
You need remote access (CKB running on a server, agents calling over the network)
You want task lifecycle management (submit → working → completed)
You're integrating with Vertex AI Agent Engine, LangChain, or other A2A-compatible platforms

Server Configuration

# Basic
ckb a2a --port 8081

# With authentication
ckb a2a --port 8081 --auth-token mytoken
# Or via environment variable
export CKB_A2A_TOKEN=mytoken
ckb a2a

# Custom host and CORS
ckb a2a --host 0.0.0.0 --port 8081 --cors-allow "*"

# Custom base URL (for reverse proxy / public URL)
ckb a2a --base-url https://ckb.example.com

# Specific repository
ckb a2a --repo /path/to/repo
ckb a2a --repo my-registered-repo

Flag	Default	Description
`--port`	`8081`	Port to listen on
`--host`	`localhost`	Host to bind to
`--auth-token`	(none)	Bearer token for authentication (env: `CKB_A2A_TOKEN`)
`--cors-allow`	(none)	Comma-separated allowed CORS origins
`--base-url`	`http://{host}:{port}`	Public base URL for agent card
`--repo`	(auto-detect)	Repository path or registry name

Agent Discovery

Any A2A client can discover CKB's capabilities by fetching the agent card:

curl http://localhost:8081/.well-known/agent-card.json

{
  "name": "CKB - Code Knowledge Backend",
  "description": "Language-agnostic codebase comprehension agent...",
  "version": "8.3.0",
  "supportedInterfaces": [
    {"url": "http://localhost:8081", "protocolBinding": "JSONRPC", "protocolVersion": "0.3"},
    {"url": "http://localhost:8081", "protocolBinding": "HTTP+JSON", "protocolVersion": "0.3"}
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true,
    "stateTransitionHistory": true
  },
  "skills": [
    {"id": "searchSymbols", "name": "searchSymbols", "description": "Search for symbols..."},
    {"id": "getArchitecture", "name": "getArchitecture", "description": "Get module structure..."},
    ...
  ]
}

The extended agent card (with full input schemas for each skill) is available at:

curl http://localhost:8081/extendedAgentCard

Protocol Bindings

CKB supports both A2A protocol bindings on the same port.

HTTP+JSON Binding

# Send a message (invoke a skill)
curl -X POST http://localhost:8081/message:send \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [{"text": "{\"skill\": \"searchSymbols\", \"params\": {\"query\": \"handleAuth\"}}"}]
    }
  }'

# Get a task by ID
curl http://localhost:8081/tasks/{taskId}

# List tasks
curl "http://localhost:8081/tasks?pageSize=10&status=TASK_STATE_COMPLETED"

# Cancel a task
curl -X POST http://localhost:8081/tasks/{taskId}:cancel

# Stream a task execution
curl -X POST http://localhost:8081/message:stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [{"text": "{\"skill\": \"getArchitecture\", \"params\": {}}"}]
    }
  }'

JSON-RPC Binding

All methods are available via JSON-RPC 2.0 at POST /:

curl -X POST http://localhost:8081/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "role": "ROLE_USER",
        "parts": [{"text": "{\"skill\": \"getStatus\", \"params\": {}}"}]
      }
    }
  }'

Available JSON-RPC methods:

Method	Description
`message/send`	Send a message, returns a completed Task
`message/sendStream`	Send with SSE streaming
`tasks/get`	Get task by ID
`tasks/list`	List tasks with pagination
`tasks/cancel`	Cancel a running task
`tasks/subscribe`	Subscribe to task updates via SSE
`tasks/pushNotificationConfig/set`	Create webhook config
`tasks/pushNotificationConfig/get`	Get webhook config
`tasks/pushNotificationConfig/list`	List webhook configs
`tasks/pushNotificationConfig/delete`	Delete webhook config
`agent/extendedCard`	Get extended agent card

Skills (CKB Tools as A2A Skills)

All 80+ CKB tools are automatically exposed as A2A skills. Skills are invoked by sending a message with a JSON body:

{"skill": "<skillName>", "params": {<tool parameters>}}

Key Skills

Skill	What it does
`searchSymbols`	Semantic code search
`getSymbol`	Get symbol definition and metadata
`findReferences`	Find all references to a symbol
`getArchitecture`	Get module structure and dependencies
`analyzeImpact`	Blast radius analysis for a symbol
`explore`	Comprehensive area exploration (compound)
`understand`	Deep-dive into a function or type (compound)
`prepareChange`	Impact analysis before modifying code (compound)
`reviewPR`	Run 21 quality checks on a PR
`auditCompliance`	Run compliance audit (GDPR, SOC2, etc.)
`reindex`	Trigger index refresh
`getStatus`	System health and index freshness

Full tool reference: See MCP-Tools — all MCP tools are available as A2A skills with the same parameters.

Task Lifecycle

A2A tasks follow this state machine:

SUBMITTED → WORKING → COMPLETED
                   → FAILED
                   → INPUT_REQUIRED → WORKING → ...
                   → AUTH_REQUIRED  → WORKING → ...
                   → CANCELED

SUBMITTED → REJECTED
SUBMITTED → CANCELED

Each task includes:

History — all messages exchanged (user requests + agent responses)
Artifacts — structured output (JSON data from CKB tools)
Status — current state with timestamp and optional message
Metadata — includes indexWarnings when the CKB index is stale

Health & Index Status

The /health endpoint provides repo initialization status, index freshness, and actionable suggestions:

curl http://localhost:8081/health

{
  "status": "healthy",
  "protocol": "a2a",
  "version": "0.3",
  "index": {
    "initialized": true,
    "exists": true,
    "fresh": false,
    "commitsBehind": 3,
    "reason": "3 commits behind HEAD"
  },
  "backends": [
    {"id": "scip", "healthTier": "available", "available": true},
    {"id": "git", "healthTier": "available", "available": true}
  ],
  "suggestions": [
    "Index is 3 commit(s) behind. Run 'ckb index' to refresh, or use the 'reindex' skill."
  ]
}

Index states and what to do:

`index.initialized`	`index.fresh`	Meaning	Action
`false`	`false`	CKB not set up	Run `ckb init && ckb index`
`true`	`false`	Index exists but stale	Run `ckb index` or invoke `reindex` skill
`true`	`true`	Everything up to date	No action needed

Task responses also include metadata.indexWarnings when the index is stale, so consuming agents can decide whether to trigger a reindex before trusting results.

Push Notifications

Configure webhooks to receive task updates:

# Create a push notification config
curl -X POST http://localhost:8081/tasks/{taskId}/pushNotificationConfigs \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.example.com/webhook",
    "authentication": {
      "schemes": ["Bearer"],
      "token": "your-webhook-token"
    }
  }'

Push notifications deliver StreamResponse events (status updates, artifact updates) as HTTP POST requests to your webhook URL with at-least-once delivery semantics.

Authentication

When --auth-token is set, all endpoints except /.well-known/agent-card.json and /health require a Bearer token:

curl -X POST http://localhost:8081/message:send \
  -H "Authorization: Bearer mytoken" \
  -H "Content-Type: application/json" \
  -d '...'

GET requests on /tasks endpoints are allowed without auth for read-only access.

Integration Examples

Python (using requests)

import requests

BASE = "http://localhost:8081"

# Discover agent
card = requests.get(f"{BASE}/.well-known/agent-card.json").json()
print(f"Agent: {card['name']} ({len(card['skills'])} skills)")

# Invoke a skill
resp = requests.post(f"{BASE}/message:send", json={
    "message": {
        "role": "ROLE_USER",
        "parts": [{"text": '{"skill": "searchSymbols", "params": {"query": "handleAuth"}}'}]
    }
})
task = resp.json()
print(f"Task {task['id']}: {task['status']['state']}")

# Check if reindex is needed
health = requests.get(f"{BASE}/health").json()
if not health["index"]["fresh"]:
    requests.post(f"{BASE}/message:send", json={
        "message": {
            "role": "ROLE_USER",
            "parts": [{"text": '{"skill": "reindex", "params": {}}'}]
        }
    })

Vertex AI Agent Engine

CKB can be registered as a remote A2A agent in Vertex AI:

from google.cloud import aiplatform

# Register CKB as an A2A agent
agent = aiplatform.Agent.create(
    display_name="CKB Code Intelligence",
    a2a_endpoint="https://ckb.example.com",
)

See also: Integration-Guide for more ideas on what you can build with CKB.

Comparison: CLI vs HTTP API vs MCP vs A2A

Feature	CLI	HTTP API	MCP	A2A
Transport	Process	HTTP REST	stdio JSON-RPC	HTTP JSON-RPC + REST
Discovery	`--help`	`/openapi.json`	`tools/list`	`/.well-known/agent-card.json`
Auth	N/A	Bearer token	N/A (local)	Bearer / OAuth2 / API Key
Streaming	N/A	N/A	Notifications	SSE
Task state	N/A	Jobs API	N/A	Full lifecycle
Push	N/A	Webhooks	N/A	Push notification configs
Best for	Scripts, CI	Custom apps	IDE integration	Agent orchestration