A2A connections and task collaboration

A2A connects agents; MCP connects tools. This guide covers the current LingXizhi local kernel endpoints, not cloud account APIs or every third-party A2A protocol revision. Registering an agent, recording a delegation, and actually executing a remote task are separate operations.

1. Start the kernel and configure authentication

Start the IDE/kernel, sign in, and verify your local license. The kernel normally listens on loopback and can choose another port after a conflict. Use the actual configuration or startup log instead of assuming a fixed port.

The global data directory is LINGXIZHI_HOME, or data beside the executable when unset. Its lxz.config.json contains server.auth_token; the kernel generates and writes one when empty. Keep this file, tokens, and authenticated command output out of public logs.

The combined router checks the local server.auth_token, a valid signed-in license, and A2A_API_KEY. Both token checks read the same Authorization: Bearer ... header, so currently set A2A_API_KEY to the same local server.auth_token in the environment that launches the kernel, then restart it. Setting an environment variable outside an already-running process has no effect. This token also grants access to other protected local APIs: share it only with trusted clients and keep the service off the public Internet.

/.well-known/agent-card.json is public. Business endpoints require the checks above. A2A_AUTH_ENABLED=false/0 is a development bypass, not the normal setup; it does not disable global authentication or license checks.

Replace these placeholders yourself; angle-bracket values are not valid credentials. Obtain your token securely from the local configuration rather than committing it into scripts:

$a2aBase = 'http://127.0.0.1:<actual-port>'
$a2aToken = '<local server.auth_token, also used as the startup A2A_API_KEY>'
$headers = @{ Authorization = "Bearer $a2aToken" }
Invoke-RestMethod "$a2aBase/.well-known/agent-card.json"

The card describes capabilities and endpoints; it does not prove your license or model credentials work. Set LXZ_PROJECT_ROOT in the kernel startup environment to the intended workspace. Otherwise tasks use the kernel process working directory.

2. Create, inspect, and cancel a task

REST request fields use camelCase. Success is wrapped as {"success":true,"data":...}; business errors commonly use HTTP 400 and {"success":false,"error":"..."}. Creation only confirms submission, not successful execution.

$body = @{ text = 'Analyze the project structure without modifying files' } | ConvertTo-Json
$created = Invoke-RestMethod "$a2aBase/api/a2a/tasks/create" -Method Post -Headers $headers -ContentType 'application/json' -Body $body
if (-not $created.success) { throw $created.error }
$taskId = $created.data.id
$contextId = $created.data.contextId
Invoke-RestMethod "$a2aBase/api/a2a/tasks/$taskId" -Headers $headers

data contains id, contextId, status, history, artifacts, and metadata. status.state uses values such as submitted, working, completed, failed, and canceled. Inspect the terminal state and results; submission is not completion. The protocol also defines input-required, auth-required, and rejected, but not every execution path emits every state.

Optional contextId associates subsequent tasks; optional skill selects a capability. Neither represents an admin role or cloud account permission.

$followUp = @{ text = 'Continue by describing each directory'; contextId = $contextId } | ConvertTo-Json
# Submit only when needed, to avoid starting duplicate work.
# Invoke-RestMethod "$a2aBase/api/a2a/tasks/create" -Method Post -Headers $headers -ContentType 'application/json' -Body $followUp

# Cancel only a task you actually want to stop:
Invoke-RestMethod "$a2aBase/api/a2a/tasks/$taskId/cancel" -Method Post -Headers $headers

Cancellation does not undo files or external side effects already produced. A terminal task may no longer be cancellable; inspect the error instead of blindly submitting another task.

3. Receive SSE events

Use GET /api/a2a/tasks/:id/stream for an existing task. The client must support a Bearer header. Browser-native EventSource cannot set it directly, and a query token does not bypass A2A authentication.

curl.exe --no-buffer --header "Authorization: Bearer $a2aToken" "$a2aBase/api/a2a/tasks/$taskId/stream"

Events include task-created, task-updated, task-completed, task-failed, and task-canceled. Parse event:, id:, and data: fields. After disconnecting, query the task state: connection closure alone is not success. The REST stream does not promise durable history replay. A late subscriber may only observe terminal state.

To submit and immediately stream, POST a JSON-RPC tasks/sendSubscribe request to /a2a/subscribe, which returns SSE. Alternatively call that method at /a2a/jsonrpc to obtain a subscription ID, then connect to /a2a/sse/:subscription_id. Task IDs and subscription IDs are different.

4. JSON-RPC requests

POST /a2a/jsonrpc uses the same authentication. Replace taskId in this request body with a real ID:

{
  "jsonrpc": "2.0",
  "id": "read-task-1",
  "method": "tasks/get",
  "params": { "taskId": "a2a_<actual-id>" }
}

Supported methods are tasks/send, tasks/get, tasks/list, tasks/cancel, tasks/sendSubscribe, tasks/pushNotification/set, and agents/card. Inspect result or error: HTTP 200 can still contain a JSON-RPC error.

Creation requires params.message with role, parts, and a Unix-seconds timestamp. A REST text body is not a valid JSON-RPC message:

{
  "jsonrpc": "2.0",
  "id": "create-task-1",
  "method": "tasks/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "Analyze without modifying files" }],
      "timestamp": 1793232000
    }
  }
}

The timestamp illustrates the format; generate current Unix seconds when sending. Push notification configuration initiates outbound HTTP calls. Check destinations and permitted data before using it; this is not a durable message queue.

5. Registration, discovery, trust, and delegation

Register an external agent description with POST /api/a2a/agents/register. This minimal body tests registration:

{
  "id": "team-review-agent",
  "name": "Team review agent",
  "version": "1.0.0",
  "organization": "example-team",
  "description": "Internal review service",
  "capabilities": [],
  "endpoints": []
}

Empty capabilities and endpoints do not enable remote execution. Real capabilities contain name, description, inputSchema, and outputSchema; endpoints contain url, protocol, and description. Protocol values must match the current kernel enum.

Discovery gives skill precedence over organization; those filters are not automatically combined. minTrustScore and capabilities are subsequently applied. Trust events include success, failure, timeout, cancelled, security_violation, endorsement, and complaint. They are caller reports, not independent verification.

Delegation requires a target trust score of at least 30. The current REST delegation endpoint returns record identifiers such as requestId and chainId; it does not itself dispatch a remote task. Success does not mean a remote agent executed or completed work. Registry trust levels and trust-engine scores are also distinct stores, not automatically synchronized.

Limits and troubleshooting

Tasks, contexts, registration, trust, and delegations are in memory and do not survive restart. Limits are 100 retained tasks, 200 subscriptions, 64 buffered events per subscription, and a 30-minute task monitor timeout. This is not durable external production orchestration. A2A request bodies are limited to 1 MiB.

Kernel API · MCP configuration

Hook automation