a2a-plugin

A CAP plugin that automatically exposes annotated CDS services as A2A (Agent-to-Agent protocol) agents.

Installation

npm add a2a-plugin

CAP activates the plugin automatically via the cds.plugin flag.

Usage

1. Annotate your CDS service

Both @a2a and @a2a.Skill are required. @a2a opts the service into the A2A protocol; without it the plugin ignores the service entirely.

@a2a.Skill: {
    id:          'my-skill',
    name:        'My Skill',
    description: 'Does something useful for an LLM caller.'
}
@a2a
service MyService {}

2. Implement the agent handler

import cds from '@sap/cds';
import { AgentRequest, getEventBus } from 'a2a-plugin/lib/types';

export default class MyService extends cds.ApplicationService {
    async init() {
        this.on('agent', async (req: AgentRequest) => {
            // Optional: publish an intermediate status update
            getEventBus()?.publish({
                kind: 'status-update',
                contextId: req.data.contextId,
                taskId:    req.data.taskId,
                final:     false,
                status:    { state: 'working' },
            });

            return 'Hello from my CAP agent!';
        });
        return super.init();
    }
}

Endpoints

The plugin mounts the following routes at /a2a/<service-path>:

| Route | Description | |---|---| | GET .well-known/agent.json | Agent card (A2A discovery) | | POST /jsonrpc | JSON-RPC 2.0 transport | | * /rest/* | HTTP+JSON REST transport |

Customising execution lifecycle

By default the plugin creates a CAPAgentExecutor internally and dispatches to your agent handler. If you need control over the full execution lifecycle — custom error handling, pre/post logic, different transport behaviour — extend CAPAgentService instead of cds.ApplicationService:

import { ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
import { AgentRequest, CAPAgentService } from 'a2a-plugin/lib/types';

export default class MyService extends CAPAgentService {

    async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
        // pre-execution logic
        await super.execute(requestContext, eventBus);
        // post-execution logic
    }

    async init() {
        this.on('agent', async (req: AgentRequest) => {
            return 'Hello from my CAP agent!';
        });
        return super.init();
    }
}

CAPAgentService extends cds.ApplicationService and implements the A2A AgentExecutor interface. When the plugin detects that the service already satisfies AgentExecutor, it uses it directly as the executor — no separate internal executor is created. Override cancelTask the same way to customise task cancellation.

Services that extend plain cds.ApplicationService continue to work exactly as before.

API

CAPAgentService

import { CAPAgentService } from 'a2a-plugin/lib/types';

Base class combining cds.ApplicationService with the A2A AgentExecutor interface. Override execute and/or cancelTask to customise the execution lifecycle. Both methods are regular prototype methods so super calls work normally.

getEventBus(): ExecutionEventBus | undefined

import { getEventBus } from 'a2a-plugin/lib/types';

Returns the ExecutionEventBus for the currently running A2A task. Only available inside an agent handler. Use it to publish streaming intermediate status updates back to the client.

AgentRequest

import { AgentRequest } from 'a2a-plugin/lib/types';

Typed alias for cds.Request<RequestContext>. Gives typed access to req.data.taskId, req.data.contextId, and req.data.userMessage.

Skill annotation reference

| Annotation | Type | Required | Description | |---|---|---|---| | @a2a.Skill.id | String | ✓ | Unique skill identifier | | @a2a.Skill.name | String | ✓ | Human-readable name | | @a2a.Skill.description | String | ✓ | Skill description for LLM prompting | | @a2a.Skill.tags | [String] | | Categorisation tags | | @a2a.Skill.examples | [String] | | Example input queries | | @a2a.Skill.inputModes | [String] | | Accepted MIME types (default: ["text/plain"]) | | @a2a.Skill.outputModes | [String] | | Produced MIME types (default: ["text/plain"]) |

Input mapping

The req.data in the agent handler is the full A2A RequestContext. The plugin also attempts to extract a plain text value from the incoming message:

• If the request has a DataPart whose body can be parsed as JSON, it is spread into req.data.
• Otherwise the first text content of the message is mapped to the first String-typed action parameter.

Security

The adapter uses the authentication method configured for the CAP service.

License

Apache-2.0