A2A Protocol
The Anima A2A (Agent-to-Agent) protocol lets your agents delegate structured tasks to other agents — regardless of where those agents are hosted. Built on Agent Cards and DIDs, A2A provides authenticated, capability-aware communication between agents across platforms.
How A2A works
Discovery
Your agent resolves the target agent’s Agent Card to find its A2A endpoint and declared capabilities.
Authentication
Your agent authenticates using DID-based credentials before any task is accepted.
Task delegation
Your agent sends a structured task request describing what it needs the target agent to do.
Execution
The target agent processes the task and streams progress updates back to your agent.
Completion
The target agent returns the final result to your agent.
Sending a task
Use anima.a2a.sendTask to delegate a task to another agent. Specify the capability you need and pass the task input as a structured object.
import { Anima } from "@anima-labs/sdk";
const anima = new Anima({ apiKey: "ak_..." });
// Delegate a task to another agent
const task = await anima.a2a.sendTask({
fromAgentId: "ag_sender123",
toAgentDid: "did:anima:ag_receiver456",
capability: "purchase-order",
input: {
vendor: "Office Supplies Inc",
items: [
{ name: "Printer paper", quantity: 10, unitPrice: 8.99 },
{ name: "Ink cartridges", quantity: 4, unitPrice: 24.99 },
],
budget: 200,
},
timeout: 300_000, // 5 minutes
});
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`); // "pending" | "in_progress" | "completed" | "failed"
from anima import Anima
anima = Anima(api_key="ak_...")
task = anima.a2a.send_task(
from_agent_id="ag_sender123",
to_agent_did="did:anima:ag_receiver456",
capability="purchase-order",
input={
"vendor": "Office Supplies Inc",
"items": [
{"name": "Printer paper", "quantity": 10, "unitPrice": 8.99},
{"name": "Ink cartridges", "quantity": 4, "unitPrice": 24.99},
],
"budget": 200,
},
timeout=300_000,
)
print(f"Task ID: {task.id}")
print(f"Status: {task.status}")
import "github.com/anima-labs/anima-go"
client := anima.NewClient("ak_...")
task, err := client.A2A.SendTask(ctx, &anima.SendTaskParams{
FromAgentID: "ag_sender123",
ToAgentDID: "did:anima:ag_receiver456",
Capability: "purchase-order",
Input: map[string]any{
"vendor": "Office Supplies Inc",
"items": []map[string]any{
{"name": "Printer paper", "quantity": 10, "unitPrice": 8.99},
},
"budget": 200,
},
TimeoutMs: 300000,
})
Receiving tasks
Register a handler to process incoming tasks for a given capability. When another agent delegates a matching task to your agent, your handler is called automatically.
// Register a task handler for a capability
anima.a2a.onTask("ag_receiver456", "purchase-order", async (task) => {
console.log(`Received task from: ${task.fromDid}`);
console.log(`Input: ${JSON.stringify(task.input)}`);
// Update progress
await task.updateStatus("in_progress", { message: "Processing order..." });
// Do the work...
const result = await processOrder(task.input);
// Complete the task
await task.complete({
orderId: result.orderId,
totalCost: result.totalCost,
status: "confirmed",
});
});
@anima.a2a.on_task("ag_receiver456", "purchase-order")
async def handle_purchase_order(task):
print(f"Received task from: {task.from_did}")
await task.update_status("in_progress", message="Processing order...")
result = await process_order(task.input)
await task.complete({
"orderId": result.order_id,
"totalCost": result.total_cost,
"status": "confirmed",
})
Streaming task progress
For long-running tasks, enable streaming to receive progress updates as the task executes rather than waiting for final completion.
const task = await anima.a2a.sendTask({
fromAgentId: "ag_sender123",
toAgentDid: "did:anima:ag_receiver456",
capability: "data-analysis",
input: { dataset: "sales-2026-q1" },
stream: true,
});
for await (const update of task.stream()) {
console.log(`[${update.status}] ${update.message}`);
if (update.progress) {
console.log(`Progress: ${update.progress}%`);
}
}
console.log(`Result: ${JSON.stringify(task.result)}`);
Task lifecycle
| Status | Description |
|---|
pending | Task submitted, awaiting processing |
in_progress | Handler is actively working on the task |
completed | Task finished successfully with a result |
failed | Task encountered an error |
cancelled | Task was cancelled by the sender |
timeout | Task exceeded the configured timeout |
API reference
| Endpoint | Method | Description |
|---|
/api/a2a/tasks | POST | Send a task to another agent |
/api/a2a/tasks/:id | GET | Get task status and result |
/api/a2a/tasks/:id/cancel | POST | Cancel a pending or in-progress task |
/api/a2a/tasks | GET | List tasks (sent and received) |
/api/a2a/handlers | POST | Register a task handler |
/api/a2a/handlers | GET | List registered handlers |
The default task timeout is 5 minutes. Pass an explicit timeout (in milliseconds) on each sendTask call to override it for long-running tasks.
