aws / aws/agentcore-cli

[TypeScript] Support A2A protocol in AgentCore CLI + serve_a2a equivalent in TS SDK

Open
#1,743 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
283
Forks
95
Avg merge
1d 2h
Merged PRs (30d)
183

Description

### Description

### Summary

The AgentCore CLI (`@aws/agentcore`) and the TypeScript SDK (`bedrock-agentcore`)
do not currently support the A2A (Agent-to-Agent) protocol, while the Python
tooling does. This forces TypeScript users into a manual workaround to deploy
an A2A agent.

### Environment

- CLI: `@aws/agentcore` (npm)
- SDK: `bedrock-agentcore` (npm, TypeScript)
- Language: TypeScript
- Protocol: A2A

### Current behavior

1. Running `agentcore` and selecting **TypeScript** offers only the default
**HTTP** protocol — there is no option to select **A2A**.
2. Selecting **Python** does offer the **A2A** protocol option.
3. The Python SDK exposes `serve_a2a` from `bedrock_agentcore.runtime`, but the
npm package `bedrock-agentcore/runtime` has no `serve_a2a` equivalent.
4. Attempting `--language TypeScript --protocol A2A` is gated at the CLI level
(per the CLI CHANGELOG: "gate MCP and A2A protocols behind Python-only until
TS templates land").

### Expected behavior

TypeScript should have parity with Python for A2A:
- `agentcore` CLI should allow selecting the **A2A** protocol for TypeScript
agents and scaffold an appropriate template.
- The TypeScript SDK should provide a `serve_a2a` equivalent (or documented
helper) that satisfies the A2A protocol contract (port 9000, `POST /`,
`GET /ping`, `GET /.well-known/agent-card.json`).

### Current workaround

A2A works with TypeScript today, but only manually:
- Implement the A2A contract using the official `@a2a-js/sdk` on port 9000.
- Register the agent as HTTP, then edit `agentcore/agentcore.json` to set
`protocol: A2A`.
- Provide a custom ARM64 Dockerfile (base `node:22-slim`, `EXPOSE 9000`).
- Deploy via `agentcore deploy` (CodeBuild handles the ECR push), or bypass the
CLI entirely with CDK (`protocolConfiguration: ProtocolType.A2A`).

This confirms the gap is a **tooling/SDK limitation, not an architectural one** —
AgentCore's A2A support is a transparent JSON-RPC proxy that is language-agnostic.

### Requests

1. Add A2A protocol support (CLI scaffolding + template) for TypeScript.
2. Add a `serve_a2a` equivalent to the TypeScript SDK.
3. Document the TypeScript A2A path in the AgentCore devguide.

### References

- Deploy A2A servers in AgentCore Runtime: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html
- A2A protocol contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a-protocol-contract.html
- A2A JS SDK: https://github.com/a2aproject/a2a-js

### Acceptance Criteria

### Acceptance Criteria

- [ ] Running the `agentcore` CLI with `--language TypeScript` offers **A2A**
as a selectable protocol (not just HTTP).
- [ ] `agentcore ... --language TypeScript --protocol A2A` no longer errors out
(the Python-only gate is removed for A2A).
- [ ] The CLI scaffolds a working TypeScript A2A template that satisfies the
A2A protocol contract (port 9000, `POST /`, `GET /ping`,
`GET /.well-known/agent-card.json`).
- [ ] The TypeScript SDK (`bedrock-agentcore`) exposes a `serve_a2a` equivalent
(or a documented helper) so users don't have to wire up `@a2a-js/sdk`
manually.
- [ ] A scaffolded TypeScript A2A agent can be deployed via `agentcore deploy`
and successfully responds to a JSON-RPC `message/send` request.
- [ ] The AgentCore devguide documents the TypeScript A2A path end-to-end.

### Additional Context

_No response_

Contributor guide

Open the contributing guide

Research direction

Start by tracing the CLI's TypeScript protocol selection and A2A gate, then inspect the TypeScript SDK runtime and the existing Python A2A behavior. Use the A2A protocol contract and @a2a-js/sdk references to define the scaffold and helper. Done means the CLI scaffolds and deploys a TypeScript agent that serves the required endpoints, handles message/send, and is documented in the devguide.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, cli, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.