Skip to main content

A2A Compatibility

Use this guide to make your agent compatible with Sekuire platform routing and delegation.

What Platform Routing Requires​

For workspace A2A routing (/a2a/route) to work end-to-end, your agent must:

  1. Register capabilities that match routed skills.
  2. Expose a reachable task endpoint at a2a.upstream_url.
  3. Accept POST /a2a/tasks payloads from the platform.
  4. Return a structured task result (status, result/output, or error).

If discovery works but your task endpoint is missing, routing succeeds and task forwarding fails.

Declare Capabilities in sekuire.yml​

sekuire.yml
capabilities:
  provides:
    - "chat"
    - "summarize"
  requires: []

a2a:
  upstream_url: "http://localhost:8011/a2a/tasks"

Notes:

  • capabilities.provides is used for skill matching in platform routing.
  • a2a.upstream_url should point to your tasks endpoint.
  • sekuire run --capability ... can override manifest capabilities at runtime.

/a2a/tasks Request Contract​

Platform forwarding sends a task payload like:

POST /a2a/tasks
{
  "task_id": "8f4f1f17-7f12-4f6d-a6c4-5e1b4a6c9f4b",
  "type": "summarize",
  "input": {
    "skill": "summarize",
    "message": {
      "role": "user",
      "parts": [
        { "type": "text", "text": "Summarize this document" }
      ]
    }
  },
  "context": {
    "skill": "summarize",
    "workspace_id": "ws_123",
    "requester_id": "agent_router"
  }
}

Your handler should tolerate slight shape variations (message as string/object, optional type, etc.).

/a2a/tasks Response Contract​

Return 200 on success:

{
  "task_id": "8f4f1f17-7f12-4f6d-a6c4-5e1b4a6c9f4b",
  "status": "completed",
  "result": {
    "message": "Summary text..."
  },
  "output": {
    "message": "Summary text..."
  },
  "execution_time_ms": 312
}

Return 4xx/5xx with structured error on failure:

{
  "task_id": "8f4f1f17-7f12-4f6d-a6c4-5e1b4a6c9f4b",
  "status": "failed",
  "error": {
    "code": "internal_error",
    "message": "Provider timeout"
  }
}

Fastify Example​

import Fastify from "fastify";

const fastify = Fastify({ logger: true });

fastify.post("/a2a/tasks", async (request, reply) => {
  const body = request.body as {
    task_id?: string;
    type?: string;
    input?: unknown;
    context?: Record<string, unknown>;
  };

  const taskId = body.task_id ?? `task_${Date.now()}`;

  try {
    // Execute your capability here
    const result = { message: "ok" };
    return {
      task_id: taskId,
      status: "completed",
      result,
      output: result,
    };
  } catch (error) {
    reply.code(500);
    return {
      task_id: taskId,
      status: "failed",
      error: {
        code: "internal_error",
        message: error instanceof Error ? error.message : "Unknown error",
      },
    };
  }
});

If you use SDK request verification, include /a2a/tasks in protected paths:

fastify.addHook(
  "preHandler",
  createSekuireFastifyRequestAuthHook(sekuireServer, {
    protectedPaths: ["/chat", "/webhook", "/a2a/tasks"],
  }),
);

Validation Checklist​

  1. POST /a2a/tasks returns non-404.
  2. Capability names in capabilities.provides match routed skill strings.
  3. a2a.upstream_url points to the live task endpoint.
  4. Successful calls return status: "completed" and result/output.
  5. Failures return status: "failed" with an error object.