diff --git a/DECISIONS.md b/DECISIONS.md index 7f25b73..949c58f 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1,11 +1,11 @@ # Architecture Decisions -This document records deliberate "won't do" decisions for the project. These are features we evaluated and chose NOT to implement — not because they're bad ideas, but because they conflict with our positioning as the **simplest multi-agent framework**. - -If you're considering a PR in any of these areas, please open a discussion first. +This document records our architectural decisions — both what we choose NOT to build, and what we're actively working toward. Our goal is to be the **simplest multi-agent framework**, but simplicity doesn't mean closed. We believe the long-term value of a framework isn't its feature checklist — it's the size of the network it connects to. ## Won't Do +These are paradigms we evaluated and deliberately chose not to implement, because they conflict with our core model. + ### 1. Agent Handoffs **What**: Agent A transfers an in-progress conversation to Agent B (like OpenAI Agents SDK `handoff()`). @@ -20,18 +20,30 @@ If you're considering a PR in any of these areas, please open a discussion first **Related**: Closing #20 with this rationale. -### 3. A2A Protocol (Agent-to-Agent) +## Open to Adoption -**What**: Google's open protocol for agents on different servers to discover and communicate with each other. +These are protocols we see strategic value in and are actively tracking. We're waiting for the right moment — not the right feature spec, but the right network density. -**Why not**: Too early — the spec is still evolving and adoption is minimal. Our users run agents in a single process, not across distributed services. If A2A matures and there's real demand, we can revisit. Today it would add complexity for zero practical benefit. +> **Our thesis**: Framework competition on features (DAG scheduling, shared memory, zero-dependency) is a race that can always be caught. Network competition — where the value of the framework grows with every agent published to it — creates a fundamentally different moat. MCP and A2A are the protocols that turn a framework from a build tool into a registry. -### 4. MCP Integration (Model Context Protocol) +### 3. MCP Integration (Model Context Protocol) **What**: Anthropic's protocol for connecting LLMs to external tools and data sources. -**Why not now**: Our `defineTool()` API lets users wrap any external service as a tool in ~10 lines of code, and adding MCP would introduce `@modelcontextprotocol/sdk` as a new dependency plus transport layer management, breaking our 3-dependency minimal principle. However, the MCP tool ecosystem has grown significantly — many services now ship MCP servers directly, and asking users to re-wrap each one via `defineTool()` creates unnecessary friction. **This decision may be revisited** when community demand is clear or a lightweight integration approach emerges (e.g., optional peer dependency). +**Status**: **Next up.** MCP has crossed the adoption threshold — Cursor, Windsurf, Claude Code all ship with built-in support, and many services now provide MCP servers directly. Asking users to re-wrap each one via `defineTool()` creates unnecessary friction. + +**Approach**: Optional peer dependency (`@modelcontextprotocol/sdk`). Zero impact on the core — if you don't use MCP, you don't pay for it. This preserves our minimal-dependency principle while connecting to the broader tool ecosystem. + +**Tracking**: #84 (planned) + +### 4. A2A Protocol (Agent-to-Agent) + +**What**: Google's open protocol for agents on different servers to discover and communicate with each other. + +**Status**: **Watching.** The spec is still evolving and production adoption is minimal. But we recognize A2A's potential to enable the network effect we care about — if 1,000 developers publish agent services using open-multi-agent, the 1,001st developer isn't just choosing an API, they're choosing which ecosystem has the most agents they can call. + +**When we'll move**: When A2A adoption reaches a tipping point where the protocol connects real, production agent services — not just demos. We'll prioritize a lightweight integration that lets agents be both consumers and providers of A2A services. --- -*Last updated: 2026-04-07* +*Last updated: 2026-04-09*