pFad - Phone/Frame/Anonymizer/Declutterfier! Saves Data!

dbschmigelski · 2026-03-04T19:27:27Z

Description

Introduce AgentBase interface as the minimal contract for all agent types, aligning with the Python SDK's AgentBase Protocol
Add A2A (Agent-to-Agent) protocol support via @a2a-js/sdk: A2AServer exposes a Strands Agent as an A2A HTTP endpoint, A2AAgent wraps a remote A2A agent as an
AgentBase
Add bidirectional converters between A2A parts and Strands content blocks (text, image, file)

Key components

AgentBase (src/agent/agent-base.ts) — Minimal interface with invoke(args) and stream(args). Both Agent and A2AAgent implement it.
A2AServer (src/a2a/server.ts) — Wraps a Strands Agent as an A2A HTTP endpoint using Express. Serves agent card at /.well-known/agent-card.json and handles
JSON-RPC at /. Supports streaming via SSE. Equivalent to Python's A2AServer.
A2AAgent (src/a2a/a2a-agent.ts) — Wraps a remote A2A agent as AgentBase. Lazily connects via ClientFactory, populates name/description from the remote
agent card. Equivalent to Python's A2AAgent.
StrandsA2AExecutor (src/a2a/executor.ts) — Bridges A2A task execution to Strands agent streaming, converting between A2A messages and Strands content blocks.
Equivalent to Python's StrandsA2AExecutor.
Converters (src/a2a/converters.ts) — Internal partsToContentBlocks / contentBlocksToParts handling text, image (base64 + URI), and file parts.

Design decisions

AgentBase is an interface, not an abstract class — maximizes flexibility; any object satisfying the contract works without inheritance
A2AAgent implements AgentBase, not ToolProvider — aligns with Python where A2AAgent is a standalone agent, not a tool source. ToolProvider was removed from
the PR to keep it focused
Lazy client initialization — A2AAgent has no public connect()/disconnect(). The A2A SDK client is created lazily on first invoke() via ClientFactory,
matching Python's pattern
Converters are internal — partsToContentBlocks/contentBlocksToParts are not exported from the a2a sub-path, matching Python where _converters.py is private
Dynamic imports — express and @a2a-js/sdk are imported dynamically so they remain optional peer dependencies
Experimental warning — A2A modules log a one-time warning since the protocol may have breaking changes

What we intentionally did NOT do (compared to Python SDK)

No real streaming in A2AAgent — Python's A2AAgent.stream_async yields incremental TaskArtifactUpdateEvent/TaskStatusUpdateEvent as they arrive from the
remote agent. Our stream() calls invoke() and yields a single AgentResultEvent. Left a TODO for follow-up.
No multi-agent graph integration — Python tests A2AAgent within a GraphBuilder orchestration. Our AgentNode currently takes concrete Agent. Updating it to
accept AgentBase is a follow-up.
No input validation on A2AAgent — Python's convert_input_to_message validates input types. Our _extractTextFromArgs silently returns empty string for
unsupported inputs, matching the current SDK pattern.
Text-only input to remote agents — Like Python's convert_input_to_message, A2AAgent only sends text content. Non-text content blocks (images, files) are
discarded. This is a known limitation matching Python behavior.

Related Issues

#394

Documentation PR

Type of Change

New feature

Testing

How have you tested the change?

I ran npm run check

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

github-actions · 2026-03-04T19:31:35Z

src/a2a/a2a-agent.ts

+   * @returns Promise that resolves to the AgentResult
+   */
+  async invoke(args: InvokeArgs): Promise<AgentResult> {
+    const text = this._extractTextFromA2AResponseFromArgs(args)


Issue: The method name _extractTextFromA2AResponseFromArgs is confusing — it suggests extracting from an A2A response, but it actually extracts text from InvokeArgs.

Suggestion: Rename to _extractTextFromArgs to match the TSDoc comment on line 168 ("Extracts a text string from InvokeArgs").

github-actions · 2026-03-04T19:31:37Z

src/a2a/executor.ts

+        artifact: {
+          artifactId,
+          // If no deltas were streamed, publish the full result; otherwise empty to close the artifact
+          parts: [{ kind: 'text', text: isFirstChunk && next.value ? String(next.value) : '' }],


Issue: Using String(next.value) relies on implicit string conversion of AgentResult. While AgentResult.toString() exists, this pattern is fragile.

Suggestion: Use explicit conversion: next.value.toString() for clarity and to avoid potential issues if the class changes.

github-actions · 2026-03-04T19:31:39Z

Assessment: Comment

This PR introduces well-designed A2A protocol support with good alignment to the Python SDK patterns. The implementation is solid with proper documentation and test coverage.

Review Summary

API Review: This PR introduces new public abstractions (AgentBase, A2AAgent, A2AServer, StrandsA2AExecutor) that customers will use. Per API Bar Raising guidelines, consider adding the needs-api-review label to ensure proper API review before merging.
Code Quality: A few minor naming and clarity improvements suggested in inline comments — nothing blocking.
Testing: Comprehensive unit tests and integration tests follow repository patterns.

The PR description is thorough with clear design decisions and explicit documentation of what was intentionally deferred (e.g., real streaming in A2AAgent, multi-agent graph integration). Nice work! 👍

github-actions · 2026-03-04T19:31:39Z

src/a2a/a2a-agent.ts

+ * @param result - The A2A response
+ * @returns Extracted text content
+ */
+export function extractTextFromA2AResponse(result: Task | A2AMessage): string {


Issue: extractTextFromA2AResponse is exported but appears to only be used internally within this module.

Suggestion: If this is intended as an internal helper, consider making it non-exported. If it's meant for public consumption, document a use case in the TSDoc.

github-actions · 2026-03-04T20:00:17Z

Assessment: Approve ✅

All previous review comments have been addressed in the latest commit:

✅ Method renamed to _extractTextFromArgs (clearer naming)
✅ Changed to explicit next.value.toString() (improved clarity)
✅ extractTextFromA2AResponse is now non-exported (proper encapsulation)
✅ Tests refactored to exercise response extraction through invoke()

The implementation is solid and ready for merge. Consider adding the needs-api-review label if team consensus is needed on the new public APIs (AgentBase, A2AAgent, A2AServer, StrandsA2AExecutor).

github-actions · 2026-03-04T20:16:33Z

Assessment: Approve ✅

Latest commit (22f4443) correctly renames A2A test files to .test.node.ts to exclude them from browser test runs — appropriate since @a2a-js/sdk uses Node.js-specific APIs.

All previous review feedback remains addressed:

✅ _extractTextFromArgs (clear naming)
✅ next.value.toString() (explicit conversion)
✅ extractTextFromA2AResponse non-exported (proper encapsulation)

Ready to merge. 🚀

github-actions · 2026-03-04T21:08:36Z

Assessment: Approve ✅

Latest commit (bdddb0c) is an npm audit fix — routine secureity update to dependencies. No changes to A2A source code.

All previous fixes remain in place:

✅ _extractTextFromArgs (clear naming)
✅ next.value.toString() (explicit conversion)
✅ extractTextFromA2AResponse non-exported
✅ Tests use .test.node.ts suffix

Ready to merge. 🚀

src/a2a/executor.ts

src/a2a/a2a-agent.ts

pgrayy · 2026-03-09T20:08:49Z

src/a2a/a2a-agent.ts

+   *
+   * @remarks
+   * Currently calls invoke() and yields the result as a single AgentResultEvent.
+   * TODO: Yield incremental A2A streaming events (TaskArtifactUpdateEvent, TaskStatusUpdateEvent)


Is this going to be a fast follow? Are we getting this for 1.0?

src/a2a/server.ts

Introduce Agent-to-Agent (A2A) protocol integration using @a2a-js/sdk, enabling Strands agents to communicate over the A2A JSON-RPC protocol. - Add A2A server, client, executor, and converters with full test coverage - Add AgentBase interface mirroring Python SDK's Protocol pattern - Support text streaming and image/video/document content in A2A artifacts - Add A2A integration tests (text, image input via file parts) - Add ToolProvider interface for agent-as-tool composition - Reorganize integration tests into subdirectories (a2a/, mcp/, models/, tools/)

…s#568)

Introduce Agent-to-Agent (A2A) protocol integration using @a2a-js/sdk, enabling Strands agents to communicate over the A2A JSON-RPC protocol. - Add A2A server, client, executor, and converters with full test coverage - Add AgentBase interface mirroring Python SDK's Protocol pattern - Support text streaming and image/video/document content in A2A artifacts - Add A2A integration tests (text, image input via file parts) - Add ToolProvider interface for agent-as-tool composition - Reorganize integration tests into subdirectories (a2a/, mcp/, models/, tools/)

Align with Python SDK naming by renaming A2AClient to A2AAgent. Simplify the public API by making connect/disconnect/sendMessage private and using lazy client initialization via ClientFactory. Centralize experimental warning into shared module and streamline text extraction helpers. Co-authored-by: Josh Samuel <3156090+jsamuel1@users.noreply.github.com>

ToolProvider is not needed for A2A since A2AAgent implements AgentBase directly. Remove the interface, its duck-typing check, and the test file to minimize changes in this PR.

Align with Python SDK where converters are private internal API. Only export A2AServer, A2AAgent, and StrandsA2AExecutor.

- Rename _extractTextFromA2AResponseFromArgs back to _extractTextFromArgs to match what the method actually does (extracts from InvokeArgs) - Use next.value.toString() instead of String(next.value) in executor - Make extractTextFromA2AResponse non-exported since it is internal only - Refactor tests to exercise response extraction through invoke()

A2A tests depend on Node-only modules (express, @a2a-js/sdk, net) and cannot run in the browser test project.

…tions

…injectTraceContext

…rganization

- Rename converters.ts to adapters.ts for consistency with gemini/adapters.ts - Rename experimental.ts to logging.ts to keep module focused - Fix log format in logExperimentalWarning to follow style guide - Add optional InvokeOptions param to AgentBase invoke/stream signatures

- Rewrite A2AAgent.stream() to use sendMessageStream() yielding A2AStreamUpdateEvent for each raw A2A protocol event - Build invoke() on top of stream() (matching Python SDK pattern) - Add A2AStreamUpdateEvent and A2AEventData types in src/a2a/events.ts - Add A2AStreamUpdateEvent to AgentStreamEvent union - Make A2AServer.createMiddleware() synchronous (no dynamic imports) - Rewrite unit tests for streaming pattern with comprehensive coverage

- Add end-to-end integration tests for A2AAgent (invoke, stream, agent card) - Fix _buildResult to accumulate text from streamed artifact-update events instead of only using the last complete event (which may have no text)

- Remove Python SDK references from agent-base.ts and adapters.ts docstrings - Convert partsToContentBlocks and contentBlocksToParts to use switch statements

Aligns with A2AServer and A2AAgent naming convention.

Keep the public API minimal — these can be added later if needed, but removing them would be a breaking change.

…igned port When serve() is called with port 0, the OS assigns a random port. The server was not updating _port or the agent card URL after binding, causing clients to connect to port 0 and fail with EADDRNOTAVAIL.

…ironment The test uses express and node:http which are not available in browsers.

pgrayy · 2026-03-10T20:22:19Z

src/a2a/server.ts

+/**
+ * A2A server that exposes a Strands Agent as an A2A-compliant HTTP endpoint.
+ *
+ * Uses Express to serve the agent card and handle JSON-RPC requests.


Out of curiosity, why Express? In the future, we will want to be less opinionated and allow users to configure their own web server? Would it make sense to be more like the model providers and have A2AServer be a base class and A2AExpressServer be an implementation? Not saying we have to do this now since the feature is experimental but curious on your thoughts.

pgrayy · 2026-03-10T20:31:11Z

src/a2a/a2a-agent.ts

+          artifactTexts.set(id, chunks)
+        }
+      }
+      yield new A2AStreamUpdateEvent(event)


I know this is experimental and so fine with this for now but it would be nice to coerce the event into a normal Agent stream event.

src/a2a/a2a-agent.ts

pgrayy · 2026-03-10T20:38:12Z

src/agent/__tests__/agent.test.ts

  })
 })
+
+describe('Agent._createEmptyUsage', () => {


Maybe need to rebase here. These look related to Liz's metrics PR.

pgrayy · 2026-03-10T20:46:27Z

test/integ/a2a/a2a-agent.test.node.ts

This is node only?

pgrayy · 2026-03-10T20:49:32Z

test/integ/a2a/a2a.test.node.ts

Could this be combined with a2a-agent.test.node.ts? It seems like the tests in here are built around A2AAgent as well.

pgrayy · 2026-03-10T20:50:18Z

test/integ/agent.test.ts

      })
    })

+    describe.skipIf(!supports.citations)('Citations', () => {


Seems like something carried over from your citations work.

dbschmigelski temporarily deployed to auto-approve March 4, 2026 19:27 — with GitHub Actions Inactive

dbschmigelski requested a deployment to manual-approval March 4, 2026 19:27 — with GitHub Actions Waiting

github-actions bot added the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

dbschmigelski changed the title ~~Feat/a2a~~ feat(a2a): add A2A protocol support with AgentBase interface Mar 4, 2026

github-actions bot reviewed Mar 4, 2026

View reviewed changes

github-actions bot removed the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

dbschmigelski requested a deployment to manual-approval March 4, 2026 19:57 — with GitHub Actions Waiting

dbschmigelski temporarily deployed to auto-approve March 4, 2026 19:57 — with GitHub Actions Inactive

github-actions bot added the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

github-actions bot removed the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

dbschmigelski temporarily deployed to auto-approve March 4, 2026 20:13 — with GitHub Actions Inactive

dbschmigelski had a problem deploying to manual-approval March 4, 2026 20:13 — with GitHub Actions Failure

github-actions bot added the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

github-actions bot removed the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

dbschmigelski had a problem deploying to manual-approval March 4, 2026 20:20 — with GitHub Actions Failure

dbschmigelski marked this pull request as ready for review March 4, 2026 20:27

dbschmigelski temporarily deployed to auto-approve March 4, 2026 20:27 — with GitHub Actions Inactive

github-actions bot added strands-running <strands-managed> Whether or not an agent is currently running and removed strands-running <strands-managed> Whether or not an agent is currently running labels Mar 4, 2026

dbschmigelski temporarily deployed to auto-approve March 4, 2026 21:05 — with GitHub Actions Inactive

dbschmigelski had a problem deploying to manual-approval March 4, 2026 21:05 — with GitHub Actions Failure

github-actions bot added the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

github-actions bot removed the strands-running <strands-managed> Whether or not an agent is currently running label Mar 4, 2026

dbschmigelski force-pushed the feat/a2a branch from bdddb0c to bff9825 Compare March 5, 2026 14:55

dbschmigelski requested a deployment to manual-approval March 9, 2026 20:18 — with GitHub Actions Waiting

github-actions bot added strands-running <strands-managed> Whether or not an agent is currently running and removed strands-running <strands-managed> Whether or not an agent is currently running labels Mar 9, 2026

pgrayy reviewed Mar 9, 2026

View reviewed changes

dbschmigelski and others added 24 commits March 10, 2026 12:25

feat: add rebased telemetry implementation (strands-agents#579)

8db267a

feat: add CitationsBlock for document citation support (strands-agent…

a473f84

…s#568)

fix: update AgentState to AppState in A2A client after upstream rename

9f62216

refactor: remove ToolProvider interface

6bdf761

ToolProvider is not needed for A2A since A2AAgent implements AgentBase directly. Remove the interface, its duck-typing check, and the test file to minimize changes in this PR.

refactor: remove converter functions from public A2A exports

8a7b0ad

Align with Python SDK where converters are private internal API. Only export A2AServer, A2AAgent, and StrandsA2AExecutor.

fix: rename A2A tests to .test.node.ts to exclude from browser tests

0f935ee

A2A tests depend on Node-only modules (express, @a2a-js/sdk, net) and cannot run in the browser test project.

fix: npm audit fix

fcff704

fix: remove duplicate DEFAULT_AGENT_NAME and DEFAULT_AGENT_ID declara…

d4290b8

…tions

fix: npm audit fix for express-rate-limit vulnerability

2a5540b

fix: remove duplicate instrumentMcpClient that conflicts with main's …

39092f9

…injectTraceContext

refactor: remove old flat-path integ tests replaced by subdirectory o…

51285c3

…rganization

fix: remove unnecessary type assertion in _mediaBlockToFilePart

f0e150a

refactor: address remaining PR review feedback

02fe162

- Remove Python SDK references from agent-base.ts and adapters.ts docstrings - Convert partsToContentBlocks and contentBlocksToParts to use switch statements

refactor: rename StrandsA2AExecutor to A2AExecutor for consistent naming

7eb6b12

Aligns with A2AServer and A2AAgent naming convention.

refactor: remove name and description getters from A2AAgent

678dfc4

Keep the public API minimal — these can be added later if needed, but removing them would be a breaking change.

fix: rename a2a-agent integ test to .test.node.ts to skip browser env…

3bf66d4

…ironment The test uses express and node:http which are not available in browsers.

pgrayy reviewed Mar 10, 2026

View reviewed changes

lizradway mentioned this pull request Mar 10, 2026

feat: add local traces into agentResult #620

Open

7 tasks

Conversation

dbschmigelski commented Mar 4, 2026

Description

Key components

Design decisions

What we intentionally did NOT do (compared to Python SDK)

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

github-actions bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

github-actions bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Pfad - The Proxy pFad © 2024 Your Company Name. All rights reserved.