docs(design): Add design proposal for Unified Remote Agent Abstraction

[yonib05]

Summary

Design proposal for MCPAgent — a new client-side agent class that implements the existing AgentBase protocol, following the same pattern A2AAgent already established. This unifies how developers interact with remote agents regardless of the underlying protocol (MCP or A2A).

Motivation

The MCP 2025-11-25 spec added sampling, tasks, and elicitation — MCP servers now behave more like agents than tool providers. Meanwhile, Strands already has A2AAgent proving that remote agents can implement AgentBase and plug into multi-agent patterns (Swarm, Graph, Agents as Tools) seamlessly.

The gap: there's no equivalent for MCP. Using a remote MCP agent looks completely different from using an A2A agent or a native Strands agent, even though conceptually it's the same thing — talking to an agent.

What this proposes

• MCPAgent implementing AgentBase, mapping MCP concepts (sampling, tasks, tools, elicitation) to __call__, invoke_async, and stream_async
• Same pattern as A2AAgent — explicit protocol choice at construction, unified interface after that
• Automatic integration with existing multi-agent patterns (Swarm, Graph, Agents as Tools) since they already accept anything satisfying AgentBase
• Capability-aware: tool-only MCP servers still work, but raise clear errors if you try agent-style invocation without sampling support

Open questions for reviewers

1. Should MCPAgent for a tool-only server still satisfy AgentBase, or raise at construction time?
2. How should we version capability checks as MCP/A2A specs evolve?
3. Should MCPAgent and A2AAgent streaming events converge on a shared shape, or stay protocol-specific?

Willingness to implement

Yes

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-537/

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under site/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!