DEV Community: PromptMaster

5 A2A Mistakes That Break Production Systems

PromptMaster — Sat, 18 Jul 2026 15:11:48 +0000

Most A2A trouble comes from a short list of avoidable mistakes. Here they are, with the fix for each.*

The five that account for most A2A trouble: never emitting a terminal state, a missing or vague Agent Card, trusting peers by default, confusing A2A with MCP, and ignoring long-running work.

Almost all of them share one root cause: treating A2A like a simple function call. It's a protocol for stateful, long-running, cross-trust collaboration.

Design for that reality and the pitfalls mostly disappear on their own.

1. Never emitting a terminal state

The symptom: a client hangs forever on a task that, internally, finished ages ago.

This is the most frequent bug in A2A implementations, and it's maddening precisely because everything looks fine from the agent's side. The work completed. The logs are clean. The agent is idle. Meanwhile the caller is still waiting, because as far as the protocol is concerned that Task never ended.

The fix: always emit a terminal event — completed, failed, or canceled — on every path, especially error paths. If a client of yours hangs, check this first. It will usually be the answer.

Every Task must reach a terminal state.*Not most tasks. Every task, on every path.*

2. A missing or vague Agent Card

The symptom: a perfectly good agent nobody ever calls.

An agent that doesn't serve its card at the well-known path is undiscoverable — clients look there, find nothing, and move on. But there's a subtler version: an agent whose skills are described vaguely is undiscoverable in practice. A skill labeled "processing" tells an orchestrator nothing about whether to use it.

The fix: serve the card, and describe skills the way you'd document a public API — stable ids, plain-language descriptions, expected inputs, the shape of returns, and an example where behavior isn't obvious.

# prove it before wiring anything else
curl https://your-agent.example.com/.well-known/agent-card.json

3. Trusting peers by default

The symptom: an agent that will do anything a caller asks, because the caller speaks A2A.

Speaking a protocol is not a credential. Treating another agent as trusted just because it can reach you is how the tools an agent exposes become the biggest attack surface in your architecture.

The fix: authenticate every request, authorize narrowly with scoped tokens, validate all incoming Parts, and rate-limit. Verify per call, not per session — the peer talking to you now may not be the one from a moment ago. The protocol gives you the mechanisms; using them is on you.

4. Confusing A2A with MCP

The symptom: awkward architecture that fights you at every turn.

Reaching for A2A to connect an agent to a database, or MCP to connect two agents, leads to designs that almost work. Wrapping an agent as a "tool" via MCP holds up right until that agent needs to ask a clarifying question, run for ten minutes, or report progress — because tools don't have a task lifecycle.

	MCP	A2A
Other end of the wire	A tool, server, or data source	An independent agent with its own skills
Unit of interaction	A tool call or resource read	A Task with a lifecycle
Direction	Vertical — reaching down	Horizontal — reaching across

The fix: ask what's on the other end. A resource? MCP. An agent? A2A. That question answers it every time.

5. Ignoring long-running work

The symptom: a system that's responsive in the demo and unusable the first time a task takes four minutes.

Building only for fast, synchronous replies breaks the moment real work shows up. And real agent work is often slow: a report takes minutes, a pipeline takes an hour, a design task pauses to ask a question.

The fix: design for the task lifecycle from the start. Stream updates with message/stream for interactive work someone is waiting on. Use push notifications for long unattended jobs rather than holding a connection open for hours. Use input-required when you need more information instead of guessing or failing.

The meta-pitfall

Look at the five together and a single root cause shows through: treating A2A like a simple function call.

It isn't. It's a protocol for stateful, long-running, cross-trust collaboration between systems you may not control. Every mistake above is what happens when you design as if the other end were a local function that returns immediately, always succeeds, and can be trusted.

Design for what it actually is, and most of these never come up.

A production-readiness checklist

Every task emits a terminal state on all paths, including errors.
The Agent Card is served, accurate, and — where trust matters — signed.
Authentication and authorization are enforced and scoped on every call.
Long-running work uses streaming or push notifications, not blocking waits.
Tasks carry correlation ids and are traceable across every agent they touch.
Clients read advertised capabilities and degrade gracefully for missing ones.
Endpoints are rate-limited, timed out, and monitored like any production service.

Operate agents like services

One last thing that isn't a bug so much as a posture. Running many agents is an operations discipline, not just a development one.

Treat each agent as a service with an owner, a version, health checks, and a place in your monitoring. Know which agents call which, so a change or outage in one can be traced to its effect on others. Keep a registry of what exists and what it does, or discovery degrades into tribal knowledge.

The organizations that scale agents well are the ones that operate them with the same rigor they bring to any production service.

Frequently asked questions

Why does my A2A client hang forever?
Almost always because the remote agent finished its work but never emitted a terminal state. Always emit completed, failed, or canceled — on every path, including error paths. It's the most common A2A bug by a wide margin.

Why is nobody calling my A2A agent?
Either it isn't serving its Agent Card at /.well-known/agent-card.json, or its skills are described too vaguely for a client to decide it's the right agent for a job. Serve the card, and write skills like public API documentation.

Can I use MCP to connect two agents?
You can wrap an agent as a tool, and it works until that agent needs to ask a clarifying question, run for ten minutes, or report progress — because tools have no task lifecycle. If the other end is an agent, use A2A.

Is it safe to trust an agent that speaks A2A?
No. Speaking the protocol is not a credential. Authenticate every request, authorize narrowly with scoped tokens, validate all incoming Parts, and rate-limit. Verify per call, not per session.

How do I handle A2A tasks that take a long time?
Stream updates with message/stream for interactive work someone is waiting on, and use push notifications for long unattended jobs. Use input-required to pause and ask when you need more information. Never design only for fast synchronous replies.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

A2A: The Complete Guide — 42 pages. 15 chapters, 5 appendices. Discovery, security, building your first agent with the SDK, orchestration patterns, extensions and AP2, production and scaling — plus a full worked example of two agents talking and a 30-day adoption path.

Independent educational content. Not affiliated with, endorsed by, or sponsored by Google, the Linux Foundation, Anthropic, or any vendor named. A2A and MCP are evolving specifications — confirm details against the official specification for your target version.

Multi-Agent Orchestration Patterns: Orchestrator, Parallel, and Peer Handoffs

PromptMaster — Sat, 18 Jul 2026 15:10:47 +0000

One agent calling another is useful. The real power appears when you compose many — and a few patterns recur everywhere.

A2A doesn't dictate an architecture, but the field has converged on a small set of orchestration patterns.

The most common is the orchestrator pattern: one agent receives a request and delegates sub-tasks to specialists, then assembles their results. Delegation can be sequential (each result feeds the next) or parallel (independent sub-tasks at once).

You don't always need a center. Because client and remote agent are just roles, agents can also hand off peer-to-peer — letting work flow to whichever agent is best suited, without a bottleneck.

The orchestrator pattern

The most common shape is a single orchestrator agent that receives a request and delegates sub-tasks to specialized remote agents, then assembles their results. The orchestrator holds the plan; the specialists do focused work.

This maps naturally onto A2A: the orchestrator is a client to each specialist, and each specialist is a remote agent exposing its skills. Nothing special is required — it's the base protocol used deliberately.

Sequential vs parallel delegation

Sequential — the orchestrator delegates step by step, feeding each agent's Artifact into the next. Use it when later work depends on earlier results.
Parallel — the orchestrator delegates independent sub-tasks at once and gathers results as they complete. Use it when sub-tasks don't depend on each other, for speed.

A worked picture: a user asks for a market report. The orchestrator delegates data-gathering to a research agent and chart-making to a visualization agent — in parallel, since neither needs the other. Both stream to completion. The orchestrator collects two Artifacts and assembles the report.

Peer delegation and handoffs

Not every system needs a central orchestrator. Agents can also delegate peer-to-peer: a support agent hands a billing question directly to a billing agent, which may in turn consult a fraud agent.

Because "client" and "remote agent" are just roles in a single interaction, any agent can delegate to any other it can discover. Handoffs like these let work flow to whichever agent is best suited, without routing everything through one bottleneck.

Choosing a shape

There is no single right architecture, only the one that matches your priorities.

Priority	Pattern	Trade-off
Control and observability	Central orchestrator	Concentrates risk in one agent
Resilience and flexibility	Peer delegation	Harder to trace end to end
Speed on independent work	Parallel fan-out	Needs aggregation and timeout strategy
Correctness on dependent work	Sequential delegation	Slower; each step waits on the last

Match the pattern to the failure you fear.*Control, or resilience — pick deliberately.*

Patterns compose

Real systems rarely use one shape in isolation. A top-level orchestrator might fan out in parallel to several specialists, one of which internally runs a short sequential pipeline of its own, while another hands off peer-to-peer to an agent it discovered at runtime.

The patterns compose because they are all just agents playing client and remote-agent roles. Start with the simplest shape that solves the problem, and layer another only when a concrete need — speed, resilience, or flexibility — calls for it.

Discovery at scale

As the number of agents grows, hard-coding endpoints stops scaling. This is where Agent Cards earn their keep: an orchestrator can select an agent by matching a task to advertised skills rather than by knowing a fixed address.

Registries and directories of A2A agents extend this further, letting systems find capable agents dynamically — the agent equivalent of service discovery in microservices.

The practical test of whether you've done this right: can you add a new specialist agent without editing the orchestrator? If yes, you're delegating by skill. If no, you're hard-coding.

Three anti-patterns

The god orchestrator — one agent that knows every other agent's internals. It defeats the point; delegate by advertised skill, not by hard-coded knowledge.
Chatty delegation — bouncing tiny messages back and forth when one well-formed task would do. Each hop adds latency and failure surface.
Silent fan-out — launching many parallel tasks with no aggregation or timeout strategy, so one slow agent stalls the whole result.

Cost and latency are real

Every delegation adds a network hop and, often, another model call. A workflow that fans across several agents can be slower and costlier than a single one.

Design with that in mind: parallelize independent work, avoid chatty back-and-forth where one well-formed task would do, and ask honestly whether a step truly needs a separate agent or could be a tool call within one.

Multi-agent is a means, not a goal. Reach for it when the specialization or scale earns its overhead — not because it sounds impressive.

Keeping orchestration observable

An orchestrated workflow is only as debuggable as its trail. Because a single request may pass through several agents, attach a correlation identifier at the top and carry it through every delegation.

Log each task's start, state changes, and result against that id. When something goes wrong three agents deep — and eventually it will — this is the difference between reading the trail and guessing.

Frequently asked questions

What is the orchestrator pattern in multi-agent systems?
One agent receives a request and delegates sub-tasks to specialized remote agents, then assembles their results. The orchestrator holds the plan; the specialists do focused work. In A2A the orchestrator is simply a client to each specialist.

When should I use parallel vs sequential delegation?
Parallel when sub-tasks don't depend on each other — it's faster. Sequential when later work needs earlier results. Most real workflows mix both.

Do I always need a central orchestrator?
No. Agents can delegate peer-to-peer, since client and remote agent are roles rather than fixed types. Peer delegation is more resilient and avoids a bottleneck, but it's harder to trace end to end.

How do orchestrators find the right agent?
By matching a task to skills advertised in Agent Cards, rather than by knowing fixed endpoints. Registries extend this further. The test: can you add a new specialist without editing the orchestrator?

Is multi-agent always better than one agent?
No. Every delegation adds a network hop and usually another model call, so multi-agent workflows can be slower and costlier. Reach for it when specialization or scale genuinely earns the overhead.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

Securing Agent-to-Agent Communication: OAuth, JWT, and Zero Trust

PromptMaster — Sat, 18 Jul 2026 14:37:48 +0000

The moment you make an agent callable over A2A, you open a door. Here's how to make sure only the right callers walk through it.

A2A builds authentication on OAuth 2.0 and JSON Web Tokens — the same standards that protect ordinary web APIs. An agent proves who it is and is granted scoped access without ever sharing a password or private credential.

An Agent Card declares which authentication schemes the remote agent requires. The client obtains the appropriate token and presents it with every request; the remote agent validates it before doing any work.

The safest default is zero trust: assume every peer is untrusted until it proves otherwise, on every request. The agent talking to you now may not be the one that talked to you a moment ago.

Why this stops being optional immediately

The moment agents from different teams or vendors interact, security stops being a later concern. When you make an agent callable over A2A, you are opening a door into whatever that agent can do — and whatever its tools can reach.

A hard-won lesson from production agent systems: the tools and endpoints an agent exposes are the biggest attack surface in the whole architecture. An agent that blindly executes what a peer sends is a liability, however well-behaved that peer is supposed to be.

How agents authenticate

The flow is standard OAuth, which is exactly the point:

The remote agent's Agent Card declares the authentication schemes it requires.
The client reads those requirements and obtains the appropriate token — typically an OAuth 2.0 access token.
The client presents the token with each request.
The remote agent validates it before doing any work.

Because this is standard OAuth, it plugs directly into existing identity providers rather than requiring a new trust system. You inherit rotation, revocation, and auditing from infrastructure you already run.

The three mechanisms

OAuth 2.0 — for obtaining and presenting scoped access tokens.
JSON Web Tokens — for compact, verifiable, signed credentials.
Signed Agent Cards — so a client can verify a card's authenticity before trusting its endpoint.

That third one deserves attention. A card tells a client where to send work and how to authenticate. An attacker who can serve a convincing card can redirect that work — so wherever trust matters, verify the card rather than taking it at face value.

Authenticate proves who; authorize decides what

Authentication proves identity. Authorization decides what that identity may do. Conflating them is how agents end up with far more access than any single task requires.

A remote agent should grant a client only the access a given task needs, and no more. Scoped tokens make this natural: a client delegating a research task receives a token good for that, not blanket access to everything the agent can do.

Least privilege matters as much between agents*as it does between users and systems.*

Zero trust, and why per-session auth isn't enough

The safest default in a multi-agent system is to assume every peer is untrusted until it proves otherwise — on every request, not once per session.

That sounds harsh until you consider what changes underneath you. An agent you call today may be operated by another team or company tomorrow. A token valid a minute ago may have been revoked. The peer on the other end of this call may not be the one from the last call.

Re-verifying identity and authorization per call is what lets agents from different trust domains collaborate without exposing each other to risk. It is simply how the rest of secure computing already works.

Building a trust boundary

Setting up authentication between agents is mostly a matter of reusing what your organization already has:

Point your agents at your existing identity provider.
Issue scoped tokens for specific skills.
Validate at the edge of every agent, before any work happens.

The boundary you build this way is the same kind that already protects your ordinary services — which means your existing security practice, tooling, and audits apply unchanged.

Five mistakes that open doors

Implicit trust. Treating any agent that speaks A2A as safe. Authenticate and authorize every caller, every time.
Over-broad tokens. Handing a peer a token that grants far more than the task needs. Scope tokens to the specific skill being used.
Unvalidated input. Acting on incoming Parts without checking them. A file or data Part from a peer is untrusted input like any other.
No rate limits. Leaving an exposed agent open to unbounded calls, whether by accident or abuse.
Session-only auth. Verifying identity once and trusting it thereafter, when the peer on the other end can change between calls.

A security checklist

Serve only signed Agent Cards where trust matters; verify them client-side.
Require authentication on every endpoint, and validate the token on every request rather than once per session.
Scope authorization to the specific task; never hand a peer broad access.
Validate and sanitize all incoming Parts before acting on them.
Rate-limit and set timeouts, and log every task with a correlation id for later tracing.

Design for the agent you cannot see

In production, some agents you interact with will be operated by other teams or companies. Assume you cannot inspect them, cannot fix them, and cannot rely on them behaving well.

Defensive clients, strict validation, and graceful degradation are what keep your system stable when a peer misbehaves. The protocol gives you the mechanisms — using them is on you.

Frequently asked questions

How does authentication work in A2A?
A2A uses OAuth 2.0 and JSON Web Tokens. The remote agent's Agent Card declares its required authentication schemes; the client obtains a scoped access token and presents it with each request; the remote agent validates it before doing any work.

What is a signed Agent Card and why does it matter?
A cryptographically signed card lets a client verify it genuinely belongs to the claimed agent. Since a card tells clients where to send work and how to authenticate, an attacker serving a fake card could redirect that work. Verify cards wherever trust matters.

Should I authenticate once per session or per request?
Per request. In a multi-agent system the peer talking to you now may not be the one from a moment ago, tokens may have been revoked, and agents may change hands between teams or companies. Per-call verification is the only safe default.

Is A2A secure by default?
The protocol provides the mechanisms — OAuth 2.0, JWT, signed cards, scoped authorization — but using them is on you. An agent that skips validation, uses broad tokens, or trusts peers implicitly is exposed regardless of what the protocol supports.

What's the biggest security risk in a multi-agent system?
The tools and endpoints your agents expose. Making an agent callable opens a door into everything it can do and everything its tools can reach. Validate every request, authenticate before acting, rate-limit, and never trust input just because it came from another agent.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

Build Your First A2A Agent in 8 Steps

PromptMaster — Sat, 18 Jul 2026 14:36:48 +0000

Making an agent speak A2A is roughly a day's work with an official SDK. Here's the path from nothing to a discoverable, secured, interoperable agent.

Making an existing agent speak A2A takes eight steps: install the SDK, define an Agent Card, implement an executor, wire the server, handle the task lifecycle, enable discovery, secure the endpoint, and test interoperability.

You rarely implement the wire protocol by hand. Official SDKs ship for Python, JavaScript, Java, Go, and .NET, and they handle JSON-RPC parsing, the task state machine, card serving, and SSE streaming.

What you write is the executor — the code that receives a task's Message, does the actual work, reports progress, and returns Artifacts.

What you're actually building

A2A adoption isn't a rewrite. You are giving an agent you already have a front door: a card that describes it, an endpoint that accepts tasks, and honest lifecycle reporting. Its model, framework, prompts, and tools stay exactly as they are.

That's worth internalizing before you start, because it changes how much you attempt on day one. The goal is not a multi-agent architecture. The goal is one agent that any compliant client can discover and drive.

Step 1 — Install the SDK

# Python example
pip install a2a-sdk

# the SDK provides server scaffolding, the Agent Card model,
# an executor interface, and the JSON-RPC + SSE plumbing

SDKs exist for Python, JavaScript, Java, Go, and .NET. Pick the one your agent already lives in — there's no benefit to introducing a new language at the protocol boundary.

Step 2 — Define your Agent Card

Describe your agent's identity and skills. This is the contract every client plans against, so write the skills the way you'd write public API docs — a stable id, a plain-language description, expected inputs, and the shape of what comes back.

{
  "name": "Research Agent",
  "description": "Gathers and summarizes sources on a topic",
  "version": "1.0.0",
  "url": "https://agent.example.com/a2a",
  "skills": [
    { "id": "research",
      "description": "Research a topic and return a sourced summary" }
  ],
  "capabilities": { "streaming": true }
}

A skill described as "processing" tells a caller nothing. Be specific here or your agent is invisible in practice.

Step 3 — Implement an executor

This is where your real logic lives, and it's the only part of the protocol you genuinely own. The executor receives a task's incoming Message, does the work — often by calling your model and your MCP tools — reports progress, and returns Artifacts.

Keep your capability inside a clean executor rather than scattered across handler code. It makes the agent easy to reason about, easy to test directly, and unaffected when the protocol layer changes underneath it.

Step 4 — Wire the request handler and server

The SDK gives you server scaffolding; you connect your executor to it and start listening for A2A calls. There's little to invent here, which is the point — the plumbing is the same for everyone, and that's what makes agents interchangeable.

Step 5 — Handle the task lifecycle

Emit working when you start, and always reach a terminal state — completed, failed, or canceled — on every path.

This is the single most common bug in first implementations: the work finishes internally, no terminal state is reported, and the caller hangs forever. If your agent might need more information, use input-required to pause and ask rather than guessing or failing.

If a client of yours hangs, check the terminal state first.*It's the answer nine times out of ten.*

Step 6 — Enable discovery

Serve the Agent Card at the well-known path. Then prove it, before you wire up anything else:

curl https://your-agent.example.com/.well-known/agent-card.json

A running agent that doesn't serve its card cannot be discovered. It doesn't matter how well it works — if clients look at the well-known path and find nothing, the agent doesn't exist as far as the ecosystem is concerned.

Step 7 — Secure the endpoint

You just opened a door. Wire the endpoint to your existing identity provider, require a scoped token on every request, and validate it before any work happens.

Because it's standard OAuth 2.0 and JWT, you inherit rotation, revocation, and auditing from infrastructure you already run — you're not inventing a private trust scheme. Validate every incoming Part, rate-limit, and never trust input just because it arrived from another agent.

Step 8 — Test interoperability

The whole point of A2A is that any compliant client can talk to your agent. So test with one as soon as it runs:

Fetch the card.
Send a message and open a task.
Watch the task move through its states.
Confirm you get a well-formed Artifact back.

If a generic A2A client can drive your agent end to end without special knowledge, you've built something that plugs into the entire ecosystem — not just your own code. That's the difference between an agent that works and an agent that's interoperable.

What the SDK handles, and what you own

	The SDK	You
Protocol	JSON-RPC parsing, task state machine, card serving, SSE streaming, transport	—
Substance	—	Skills you declare, executor logic, tools it calls, auth policy you enforce

Keeping that division clean means protocol changes rarely touch your logic, and your logic rarely has to think about the protocol.

From hello-world to useful

A first agent that echoes a message proves the plumbing. A useful one does real work behind the same interface.

The step between them is almost entirely in the executor: wire it to your model, give it the MCP tools it needs, and have it report honest progress and return well-formed Artifacts. Keep the protocol surface unchanged as you add capability, so the agent stays interoperable while it grows more capable.

Frequently asked questions

How long does it take to make an agent speak A2A?
Roughly a day with an official SDK for an agent you already have. The SDK handles the protocol; you write the executor and the card. The first hello-world server comes together in well under an hour.

Which languages have A2A SDKs?
Official SDKs ship for Python, JavaScript, Java, Go, and .NET. Use whichever your agent already lives in.

Do I need to rewrite my agent to adopt A2A?
No. A2A is a messaging layer, not a framework. You give your existing agent an Agent Card and an A2A endpoint; its model, framework, prompts, and internal logic stay exactly as they are.

What is an A2A executor?
The function that handles an incoming task: it receives the task's Message, does the actual work (often calling your model and MCP tools), reports progress, and returns Artifacts. It's the part you write — the SDK handles everything around it.

How do I know my agent is actually interoperable?
Drive it with a generic A2A client, not your own harness. Fetch the card, open a task, watch the states, and confirm a well-formed Artifact comes back. If a client that knows nothing about your code can complete a task, you're interoperable.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

Understanding the A2A Task Lifecycle (and the Bug That Hangs Every Client)

PromptMaster — Sat, 18 Jul 2026 07:36:53 +0000

A2A is task-centric. Once a client sends work, that work becomes a Task with a lifecycle you can observe from submission to completion — if your agent reports it honestly.

A Task is the central, stateful unit of work in A2A. It is created when a client sends its first Message and moves through defined states until it reaches a terminal one.

The states are: submitted, working, input-required, completed, failed, and canceled. The last three are terminal.

The rule that matters most: every Task must reach a terminal state. A client that never hears one waits forever — and that is the single most common bug in early A2A implementations.

Why A2A models tasks instead of calls

The instinct from REST is to treat each call as independent: send a request, get a response, done. Agent work rarely behaves like that.

A report might take minutes. A data pipeline might take an hour. A design task might need a clarifying question halfway through. Modeling all of that as a single request-response call means pretending every call returns at once — and then bolting on workarounds when it doesn't.

A2A models it honestly instead: work becomes a Task with an explicit state machine, so both sides always agree on where things stand.

The six states

submitted — the Task has been received but work has not yet begun.
working — the remote agent is actively processing the Task.
input-required — the agent needs more information and is waiting on the client before it can continue.
completed — the Task finished successfully; Artifacts are available.
failed — the Task ended in error.
canceled — the Task was stopped by request.

The last three are terminal: once a Task reaches one, it is over.

The four methods you need

A client starts a Task by sending a Message; the response carries the Task, including its identifier and current state. From there:

message/send     # send a message; create or continue a task
message/stream   # send a message and subscribe to live updates
tasks/get        # retrieve a task's current state and artifacts
tasks/cancel     # cancel an in-progress task

That's the whole surface. Most of the protocol's power comes from what these four methods operate on — a stateful, observable Task — not from method count.

input-required is a feature, not an error

Real delegation is rarely one-shot. The input-required state lets a remote agent pause and ask a clarifying question mid-task, then resume when the client answers.

Follow one task through to see it: a client asks an agent to generate a report; the task is created as submitted. The agent begins and moves it to working. Partway through it realizes it needs a date range, so it moves the task to input-required and asks. The client supplies the range; the task returns to working. When the report is ready, the agent attaches it as an Artifact and moves the task to completed.

event: task state -> working
event: message  -> "Which time range should I cover?"
event: task state -> input-required

# client replies on the SAME task
event: task state -> working
event: task state -> completed

Same task throughout. No new task, no lost context. That turns a rigid call into a genuine collaboration.

The bug that hangs every client

Here it is, plainly: a remote agent finishes its work but never reports a terminal state, so the client waits indefinitely.

The work completed. The logs look fine. The agent is idle and happy. And the caller is still sitting there, because as far as the protocol is concerned, that Task never ended.

Always emit a terminal event — including on error paths, especially on error paths. If a client of yours hangs, this is the first thing to check, and it will usually be the answer.

Every Task must reach a terminal state.*Not most tasks. Every task, on every path.*

Three ways to track a task

The underlying Task is identical in all three; only how you receive updates changes.

	When to use	How
Polling	Simple, short work where live progress doesn't matter	Call `tasks/get` by task id
Streaming	Interactive work someone is waiting on	`message/stream` over Server-Sent Events
Push notifications	Long, unattended work — minutes to hours	Register a callback; disconnect; get notified on state change

For the longest jobs, prefer push notifications over holding a stream open for hours. You avoid a fragile long-lived connection and the task model doesn't change.

Why an explicit lifecycle pays off

Modeling tasks as stateful, observable objects is what makes A2A suitable for real work rather than toy demos:

You can build dashboards showing every in-flight task.
You can write retry logic that reacts to failed states.
You can build orchestration that waits on completed before triggering the next step.
You can trace a failure across every agent a task touched, instead of guessing.

The lifecycle is not bureaucracy. It is the observability layer that lets multi-agent systems be operated, not just launched.

Contexts group related tasks

Real work is rarely a single task. A2A lets related tasks share a context, so an agent can connect a follow-up request to earlier ones and reason about the whole thread rather than each request in isolation.

This is what turns a sequence of one-off delegations into a coherent, ongoing collaboration — the agent equivalent of remembering the conversation so far.

Frequently asked questions

What are the A2A task states?
submitted, working, input-required, completed, failed, and canceled. The last three are terminal — once a task reaches one, it's over.

What does input-required mean in A2A?
The remote agent needs more information and has paused, waiting on the client. It's a feature, not an error: it lets an agent ask a clarifying question mid-task and resume on the same task when the client answers.

Why does my A2A client hang forever?
Almost always because the remote agent finished its work but never emitted a terminal state. The protocol has no way to know the task ended, so the client keeps waiting. Always emit completed, failed, or canceled — on every path, including errors.

Should I poll or stream A2A tasks?
Poll with tasks/get for simple short work. Stream with message/stream for interactive work someone is waiting on. Use push notifications for long unattended jobs where holding a connection open for hours is wasteful.

Is an A2A task the same as an HTTP request?
No. An HTTP request is stateless and returns once. An A2A task is stateful, can run for a long time, can pause for input, and can stream many updates before reaching a terminal state.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

The Agent Card: How AI Agents Discover Each Other

PromptMaster — Sat, 18 Jul 2026 07:36:01 +0000

Before one agent can delegate to another, it has to find it and know what it can do. The Agent Card is how.

The Agent Card is a JSON document that describes an A2A agent: its identity, endpoint, authentication requirements, and — most importantly — the skills it offers.

It is published at a well-known path, /.well-known/agent-card.json, so any client that knows an agent's base address can fetch it and immediately learn how to work with that agent.

It is the first thing a client fetches and the contract it plans against. An agent that doesn't serve a card is undiscoverable; an agent whose skills are described vaguely is undiscoverable in practice.

Why discovery has to come first

Before a client can send any work, it needs to know three things: that a remote agent exists, what it is capable of, and how to talk to it. Without a standard way to answer those questions, you're back to hard-coding endpoints and reading someone else's documentation by hand.

The Agent Card answers all three in one fetch. It is a JSON document the remote agent publishes so that any client — including one built by a team that has never spoken to yours — can read its identity and capabilities without a private arrangement.

Where the card lives

By convention, an agent serves its card at a well-known path, the same idea as the web's well-known URLs. This is what makes discovery predictable rather than a matter of asking around:

# fetch a remote agent's public card
curl https://agent.example.com/.well-known/agent-card.json

If you can't curl the card back, nothing else works. This is the single most common first-run mistake: a perfectly good agent, running fine, that no client can find because the card isn't served where clients look.

What the card contains

Identity — a name, description, provider, and version for the agent.
Endpoint — the URL where the agent receives A2A requests.
Skills — the discrete capabilities the agent offers, each with an id, description, and often example inputs and outputs.
Authentication — the security schemes the agent requires, so a client knows how to authenticate before sending work.
Capabilities — protocol features the agent supports, such as streaming or push notifications.

A minimal card

{
  "name": "Research Agent",
  "description": "Gathers and summarizes sources on a topic",
  "version": "1.2.0",
  "url": "https://agent.example.com/a2a",
  "skills": [
    { "id": "research",
      "description": "Research a topic and return a sourced summary" }
  ],
  "capabilities": { "streaming": true }
}

Skills are the part that matters most

The skills list is the heart of the card. It is what lets a client — or an orchestrating agent choosing among many — decide whether this agent is the right one for a job.

A skill described as "processing" tells a caller nothing. One described as "extract line items from an invoice PDF and return them as structured data" tells a caller everything. The difference is whether your agent gets used.

Give each skill a stable id and a plain-language description.
State the inputs it expects and the shape of what it returns.
Include a concrete example where the behavior is not obvious.

Treat skill descriptions like public API docs.*To the rest of the ecosystem, that is exactly what they are.*

Public and authenticated cards

An agent can expose a basic public card to anyone and a richer, authenticated card to clients that have proven their identity.

The public card is enough to discover the agent and learn how to authenticate. The authenticated card can reveal additional skills or detail reserved for trusted callers. This two-tier approach lets an agent be discoverable without exposing everything it can do to the entire internet.

Signed cards and trust

As the protocol matured, support for cryptographically signed Agent Cards was added, letting a client verify that a card genuinely belongs to the agent it claims to.

This matters more than it sounds. A card tells a client where to send work and how to authenticate — an attacker who can serve a convincing card can redirect that work. In any setting where trust matters, prefer verifiable cards over ones taken at face value.

Keeping cards current

An Agent Card is a living document. When you add a skill, change an endpoint, or alter your auth requirements, the card must move with the agent — a stale card sends clients to the wrong place or hides new capability.

Version your card alongside your agent, and treat a card change as part of shipping, not an afterthought. Clients read the version and capabilities you advertise, so keeping them honest is what keeps interoperability working.

Discovery at scale

As the number of agents grows, hard-coding endpoints stops scaling. This is where cards earn their keep: an orchestrator can select an agent by matching a task to advertised skills rather than by knowing a fixed address.

Registries and directories of A2A agents extend this further, letting systems find capable agents dynamically — the agent equivalent of service discovery in microservices. The practical upshot: a new specialist agent can join your system without anyone editing the orchestrator.

Frequently asked questions

What is an A2A Agent Card?
A JSON document describing an A2A agent's identity, endpoint, authentication requirements, and skills. It's published at /.well-known/agent-card.json so any client can discover the agent and learn how to work with it.

Where is the Agent Card served?
At the well-known path /.well-known/agent-card.json on the agent's host, following the same convention as other well-known URLs on the web.

What happens if my agent doesn't serve a card?
It's undiscoverable. Clients look at the well-known path; if there's nothing there, they can't find the agent, learn its skills, or know how to authenticate — no matter how well the agent works internally.

What is a signed Agent Card?
A cryptographically signed card that lets a client verify it genuinely belongs to the agent it claims to. Since a card tells clients where to send work, verification matters wherever trust does.

How do I write good skill descriptions?
Like public API documentation: a stable id, a plain-language description of what the skill does, the inputs it expects, the shape of what it returns, and a concrete example when behavior isn't obvious. Vague skills make an agent invisible in practice.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

What Is the Agent2Agent Protocol? A Complete Introduction to A2A

PromptMaster — Sat, 18 Jul 2026 07:34:48 +0000

An open standard lets AI agents from any framework discover each other, delegate work, and collaborate securely. Here's what it is, how it works, and why it matters.

A2A (Agent2Agent) is an open protocol for agent-to-agent communication. It lets independent AI agents discover each other, delegate tasks, and exchange results securely — regardless of which framework or vendor built them.

It was introduced by Google in April 2025, contributed to the Linux Foundation, and has reached a stable 1.0 release with core data models frozen. Official SDKs ship for Python, JavaScript, Java, Go, and .NET.

Under the hood it reuses standards you already know: HTTP for transport, JSON-RPC 2.0 for requests, Server-Sent Events for streaming, and OAuth 2.0 for authentication. A2A is not a framework — it sits between agents as a messaging layer, so you keep your existing stack.

The problem it exists to solve

You have probably built or used an AI agent that does one job well. A customer-service agent answers questions. A research agent gathers sources. A scheduling agent books meetings. Each is capable on its own — and each is trapped inside its own platform.

The research agent cannot tell the writing agent that the research is done. The support agent cannot hand a refund off to the billing agent. Agents have been smart individually and mute collectively.

The reason is simple: there has been no shared language. Every agent framework invented its own way of representing tasks, messages, and results. Connecting two agents built on different frameworks meant writing custom glue code for every pair — a brittle integration that broke whenever either side changed.

That does not scale. Multiply it across a dozen agents from a dozen teams and the integration burden grows quadratically. The agents are not the bottleneck; the connections between them are.

The lesson A2A borrowed from the web

We have solved this shape of problem before. The web did not scale because every server spoke a private dialect — it scaled because HTTP gave every server and client a common, framework-agnostic contract. You can point any browser at any web server because both agree on the protocol, not the implementation.

A2A applies the same idea to agents: a thin, shared protocol so an agent built on any framework can talk to an agent built on any other, without either revealing its internals.

A2A is to AI agents what HTTP is to web services.*A common protocol, not a common implementation.*

What the protocol actually standardizes

At its core, A2A defines how one agent (the client) asks another agent (the remote agent) to do work, and how results flow back. It standardizes four things every collaboration needs:

Discovery — how an agent advertises who it is and what it can do, so others can find and evaluate it.
Task delegation — how a client submits a unit of work and how its progress is tracked to completion.
Communication — how the two agents exchange messages and structured results during the work.
Security — how agents authenticate to each other and authorize access without sharing credentials.

One clarification that saves confusion later: client and remote agent are roles, not types. The same agent can be a client when it delegates work and a remote agent when it receives it. In a multi-agent system, agents constantly switch roles depending on who is asking whom.

The five building blocks

Almost everything in A2A is assembled from five concepts. Learn these and the rest of the protocol reads like plain English.

1. The Agent Card

A JSON document describing an agent: its identity, where to reach it, how to authenticate, and — most importantly — what it can do, expressed as a list of skills. By convention it lives at a well-known path so any client can find it:

curl https://agent.example.com/.well-known/agent-card.json

2. The Task

The central unit of work. When a client asks a remote agent to do something, that request becomes a Task with its own identifier and a lifecycle you can track from start to finish. Tasks are stateful: they move through defined states, can run for a long time, and can stream updates along the way.

3. The Message

A single communication turn between the client and the remote agent — a request, a reply, a clarifying question. Each Message carries a role and one or more Parts.

4. The Parts

Typed content inside a Message: a text part for prose, a file part for documents or images, a data part for structured payloads. This typing is what lets agents exchange more than plain strings.

5. The Artifact

The durable output a completed Task produces — a report, an image, a dataset. Where Messages are the conversation, Artifacts are the deliverables.

A client discovers an agent via its card, sends a Message to open a Task, exchanges more Messages as the work proceeds, and receives Artifacts as the Task completes. Five nouns, one clean flow.

Built on boring, proven standards

A2A is deliberately unglamorous under the hood, and that is a feature. It reuses the same battle-tested standards that already run the internet:

HTTP(S) for transport.
JSON-RPC 2.0 for structured requests and errors.
Server-Sent Events for streaming live task updates.
OAuth 2.0 and JSON Web Tokens for authentication.

Nothing exotic. Any engineer who has built a web service already knows the primitives, and every debugging tool they already use works unchanged. That conservatism is a large part of why the protocol was production-ready so quickly.

Who governs A2A, and why that matters

A2A was introduced by Google in April 2025 and quickly moved out of any single company's control: it was contributed to the Linux Foundation, which now governs it as a vendor-neutral standard.

This is not a detail. A protocol controlled by one company gives every competitor a reason to hold back — and agent interoperability is worthless if half the ecosystem refuses to adopt it. Neutral governance removed that objection, which is why you now find A2A supported inside Microsoft Copilot Studio, Azure AI Foundry, Amazon Bedrock AgentCore, and Google ADK simultaneously.

It reached a stable 1.0 release with core data models frozen. New capability arrives as extensions rather than breaking changes, so what you build against stays standing.

How A2A relates to MCP

If you know the Model Context Protocol, the cleanest way to place A2A is alongside it. MCP connects an agent to tools, data, and context — it answers "how does my agent use a resource?" A2A connects an agent to other agents — it answers "how does my agent work with another agent?"

They are complementary, not competing, and both are now governed under the same foundation. Most serious systems use both: MCP to give each agent its capabilities, A2A to let those agents collaborate.

MCP gives an agent hands.*A2A gives it colleagues.*

What A2A is not

It helps to draw the boundary clearly:

Not a framework. A2A does not replace LangGraph, CrewAI, or whatever you use. It sits between agents as a messaging layer.
Not a model or a runtime. It does not decide how your agent thinks or what it can do.
Not a replacement for MCP. Different problem, designed to coexist.
Not a message queue or integration bus. It is narrowly a protocol for one agent to discover, delegate to, and collaborate with another.

Everything it deliberately leaves out is something a framework, model, or companion protocol already handles better. That restraint is why it composes so cleanly.

Frequently asked questions

What is the Agent2Agent protocol?
A2A (Agent2Agent) is an open protocol for agent-to-agent communication. It lets independent AI agents discover each other, delegate tasks, and exchange results securely, regardless of which framework or vendor built them. It was introduced by Google in April 2025, is governed by the Linux Foundation, and has reached a stable 1.0 release.

Who created A2A and who controls it now?
Google introduced A2A in April 2025 and contributed it to the Linux Foundation, which now governs it as a vendor-neutral open standard. No single company controls it.

Is A2A production ready?
Yes. A2A reached a stable 1.0 release with core data models frozen, ships official SDKs for Python, JavaScript, Java, Go, and .NET, and is supported inside Microsoft Copilot Studio, Azure AI Foundry, Amazon Bedrock AgentCore, and Google ADK.

Do I need to rewrite my agents to use A2A?
No. A2A is not a framework — it's a messaging layer between agents. Adoption means giving an agent an Agent Card and an A2A endpoint. Its internals, model, and framework stay exactly as they are.

What's the difference between A2A and MCP?
MCP connects an agent to tools, data, and context. A2A connects agents to each other. MCP is vertical; A2A is horizontal. They're complementary and most production systems use both.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

A2A vs MCP: The Two Protocols Behind Every Serious AI Agent System

PromptMaster — Sat, 18 Jul 2026 07:33:23 +0000

One connects an agent to its tools. The other connects agents to each other. Confusing them is the fastest way to build an architecture that fights you.

MCP (Model Context Protocol) connects a single AI agent to tools, data, and context. It answers: how does my agent use a resource — read a file, query a database, call an API?

A2A (Agent2Agent) connects agents to other agents. It answers: how does my agent delegate work to another agent, and get results back?

MCP is vertical — an agent reaching down to its capabilities. A2A is horizontal — an agent reaching across to its peers. They are complementary, not competing. Both are open standards governed by the Linux Foundation, and most production systems run both.

Why this question keeps coming up

Ask around and you'll hear A2A and MCP discussed as if they were rivals — as though picking one is a strategic decision with a winner. It isn't. The two protocols do not overlap, and the reason people think they might is that both showed up around the same time, both are about connecting agents to something, and both are open standards with big names behind them.

But once you know what sits on the other end of each connection, the confusion dissolves permanently. That's what this piece is for.

What is MCP?

MCP — the Model Context Protocol — is an open standard for connecting an AI agent to tools, data sources, and context. When an agent needs to read a file, query a database, hit an API, or pull in a document, MCP is the layer that makes that possible in a standardized way rather than through bespoke integration.

Before MCP, every agent framework had its own notion of a "tool," and wiring an agent to a data source meant writing an adapter specific to both. MCP made that connection a protocol, so a tool exposed once works with any agent that speaks it.

MCP is what gives an individual agent its capabilities. An agent without MCP (or something like it) can think, but it cannot reach anything.

What is A2A?

A2A — Agent2Agent — is an open protocol for agent-to-agent communication. It lets independent agents discover each other, delegate tasks, and exchange results securely, regardless of which framework or vendor built them.

A2A was introduced by Google in April 2025 and contributed to the Linux Foundation, which now governs it as a vendor-neutral standard. It has since reached a stable 1.0 release with core data models frozen. Official SDKs ship for Python, JavaScript, Java, Go, and .NET, and the protocol is supported inside Microsoft Copilot Studio, Azure AI Foundry, Amazon Bedrock AgentCore, and Google ADK.

Under the hood it is deliberately unglamorous: HTTP for transport, JSON-RPC 2.0 for structured requests, Server-Sent Events for streaming updates, and OAuth 2.0 with JWTs for authentication. Nothing exotic — which is exactly why adoption moved fast.

The five things A2A is made of

Agent Card — a JSON document describing an agent's identity, endpoint, authentication, and skills, published at /.well-known/agent-card.json so others can discover it.
Task — the central, stateful unit of work, with a lifecycle you can track from submission to completion.
Message — a single turn of communication between two agents.
Parts — typed content inside a Message: text, file, or structured data.
Artifact — the durable output a completed Task produces.

A client discovers an agent via its card, sends a Message to open a Task, follows that Task through its states, and collects Artifacts when it completes. Five nouns, one flow — that's most of the protocol.

A2A vs MCP: the comparison

	MCP	A2A
Scope	Agent to tool and context	Agent to agent collaboration
Question it answers	How does my agent use this resource?	How does my agent work with that agent?
Other end of the wire	A tool, server, or data source	An independent agent with its own skills
Unit of interaction	A tool call or resource read	A Task with a lifecycle
Direction	Vertical — reaching down	Horizontal — reaching across
Governance	Open standard, Linux Foundation	Open standard, Linux Foundation

MCP gives an agent hands.*A2A gives it colleagues.*

How they layer in a real system

Picture a market-report system in two planes.

Horizontally, over A2A: a user asks an orchestrator agent for a report. The orchestrator delegates data-gathering to a research agent and chart-making to a visualization agent — discovering each by its Agent Card, authenticating with a scoped token, and streaming each Task to completion.

Vertically, over MCP: the research agent queries live data sources; the visualization agent calls a rendering tool. Each is reaching down to the capabilities it needs.

Results flow back up as Artifacts, and the orchestrator assembles the report. Two planes, each doing one job, combining into something neither could do alone. A2A moved the work between agents; MCP fed each agent the context it needed.

When do you need both?

Use MCP alone if your agent uses tools but never delegates to another agent. A single capable assistant with database access needs no A2A.
Use A2A alone for a pure router that forwards tasks between agents and holds no tools of its own. Rare, but real.
Use both when an agent needs to act on resources and collaborate with peers — which describes essentially every multi-agent system of any ambition.

The goal is a system as simple as the problem allows. Don't reach for A2A because multi-agent sounds impressive: every delegation adds a network hop and usually another model call. Reach for it when specialization or scale genuinely earns that overhead.

Why the pairing is the durable bet

Standards win when they compose. HTTP did not have to also be HTML — each did one job, and together they carried the web. A2A and MCP follow the same logic, which is why betting on the pair is safer than betting on any single framework.

Here's the part worth internalizing: an agent that speaks A2A exposes only its card and its skills. Everything behind that surface is private — which model it calls, which framework it runs on, which tools it reaches through MCP, how its logic is written. Replace any of those and every caller is unaffected, because none of them ever depended on it.

Models will improve. Frameworks will be replaced. A catalog of well-described agents that speak an open protocol stays callable through all of it. The protocol is the stable interface; everything underneath can evolve freely.

Common mistakes

Using A2A to reach a database. If the other end is a resource, it's MCP. Ask what's on the other end — that answers it every time.
Using MCP to connect two agents. Wrapping an agent as a "tool" works until that agent needs to ask a clarifying question, run for ten minutes, or report progress. Tasks exist for a reason.
Treating A2A like a function call. It's a protocol for stateful, long-running, cross-trust collaboration. Design for that and most problems disappear.
Trusting peers by default. An agent that speaks A2A is not automatically safe. Authenticate every request, authorize narrowly, validate all input, rate-limit.

Frequently asked questions

What is the difference between A2A and MCP?
MCP connects a single agent to tools, data, and context — it answers how an agent uses a resource. A2A connects agents to other agents — it answers how one agent delegates work to another. MCP is vertical; A2A is horizontal. They are complementary, and most production systems use both.

Is A2A a replacement for MCP?
No. They solve different problems and are designed to coexist. They never overlap, because they meet at the agent — which speaks A2A outward to peers and MCP downward to its tools. Both are governed under the Linux Foundation.

Is A2A production ready?
Yes. A2A reached a stable 1.0 release with core data models frozen, is governed by the Linux Foundation as a vendor-neutral standard, ships official SDKs for five languages, and is supported inside Microsoft Copilot Studio, Azure AI Foundry, Amazon Bedrock AgentCore, and Google ADK.

Do I have to rewrite my agents to adopt A2A?
No. A2A is not a framework — it's a messaging layer between agents. You keep your existing stack. Adoption means giving an agent an Agent Card and an A2A endpoint; its internals stay exactly as they are.

Which should I learn first?
MCP, if you're starting from a single agent — give it hands before you give it colleagues. A2A, if you already have capable agents that can't talk to each other, because that's the wall you're hitting.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

EARS: five patterns for requirements agents can't misread

PromptMaster — Thu, 09 Jul 2026 15:25:18 +0000

Constrained syntax, zero ambiguity

EARS (Easy Approach to Requirements Syntax) came out of Rolls-Royce in 2009 for safety-critical engine control. Five patterns, fixed clause order:

Ubiquitous:  The <system> shall <response>
Event:       When <trigger>, the <system> shall <response>
State:       While <state>, the <system> shall <response>
Unwanted:    If <cond>, then the <system> shall <response>
Optional:    Where <feature>, the <system> shall <response>

Why it maps so well to code

Each class implies its implementation and test shape:

Ubiquitous → invariants
Event → handlers + integration tests
State → state machines
Unwanted → error paths

The requirement's class tells the agent what kind of code and test it demands. Constrained syntax is context an agent cannot misread.

The compound-requirement smell

A requirement with "and" joining two behaviours is two requirements sharing a number — the agent may do one and skip the other while the line reads as done. Split it: one requirement, one behaviour, one verdict.

Try it in five minutes

Rewrite one spec's requirements into EARS. A requirement that resists every pattern usually isn't one requirement — the exercise is diagnostic by itself.

Free cheat sheet: the whole method on a few pages — the loop, spec anatomy, EARS, right-sizing — SDD Cheat Sheet.

Go deeper: the full reference — every phase, the tool landscape, three walkthroughs — Spec-Driven Development: The Complete Guide.

Anyone using EARS in their specs yet? Which pattern do you reach for most? 👇

How to write a spec an AI agent will actually follow

PromptMaster — Thu, 09 Jul 2026 15:24:49 +0000

A good spec is short

Precise enough that implementation can't silently diverge; short enough that a human actually reviews it. Skeleton:

## Intent        why this exists, in one or two lines
## Scenarios     concrete user journeys (who does what)
## Requirements  numbered, testable (EARS)
## Acceptance    observable criteria that define done
## Edge cases    the failure modes you care about
## Constraints   performance, compliance, stack bounds
## Non-goals     what this feature is NOT

If a requirement can't fail, it's a wish

Each requirement must be specific enough to point at the running system and say "satisfied" or "not satisfied" with no debate.

The two most-skipped sections

Edge cases — agents handle the happy path unprompted; the edges are where unstated intent dies. State them.
Non-goals — the difference between building what you scoped and building what the feature name vaguely implies.

Written with the agent, owned by you

Let the specify phase draft it — then cut, correct and sharpen. An unreviewed spec is paperwork, not alignment.

Free cheat sheet: the whole method on a few pages — the loop, spec anatomy, EARS, right-sizing — SDD Cheat Sheet.

Go deeper: the full reference — every phase, the tool landscape, three walkthroughs — Spec-Driven Development: The Complete Guide.

What's the one section you always forget in a spec? Mine used to be non-goals. 👇

The four phases of Spec-Driven Development

PromptMaster — Thu, 09 Jul 2026 15:24:20 +0000

Four artifacts, four gates

SPECIFY   -> spec.md   scenarios, requirements, acceptance, non-goals
PLAN      -> plan.md   architecture, data models, risks, dependencies
TASKS     -> tasks.md  atomic, ordered, verifiable, file paths
IMPLEMENT -> code      task by task, validated against the spec

What each phase is for

Specify — the what. No implementation detail; capture what the system must do and how you'll know it does.
Plan — the how. Where your stack and conventions enter. Reviewing it is where architectural mistakes die cheaply.
Tasks — the steps. One atomic, verifiable task at a time beats "build the feature" by a mile.
Implement — the code, checked against acceptance criteria written before any code existed.

The gates are the method

Each phase ends with a human review before the next begins. Skip them and you've got vibe coding with extra files. The artifacts exist to make review possible when errors are cheapest to fix.

It's a loop, not a line

Implementation reveals a gap in the plan; the plan reveals an ambiguity in the spec. Edit upstream, regenerate downstream. However your tool names the phases, the invariant is the loop.

Free cheat sheet: the whole method on a few pages — the loop, spec anatomy, EARS, right-sizing — SDD Cheat Sheet.

Go deeper: the full reference — every phase, the tool landscape, three walkthroughs — Spec-Driven Development: The Complete Guide.

Which phase does your team skip most — and has it burned you yet? 👇

Spec-Driven Development: the fix for vibe coding drift

PromptMaster — Thu, 09 Jul 2026 15:23:49 +0000

The problem with vibe coding

Left to infer intent from a casual prompt, an agent guesses: it invents an API, picks a data shape you didn't want, skips the edge case you cared about. Each guess is small. Over a feature they compound into drift — because intent was never written anywhere you could check against.

What SDD does

Write a structured spec first, then let the agent implement against it through a loop:

SPECIFY   -> spec.md   what + acceptance      [review]
PLAN      -> plan.md   architecture + risks   [review]
TASKS     -> tasks.md  atomic, ordered        [review]
IMPLEMENT -> code      task by task, vs spec

Fixes flow upstream: wrong intent → spec, wrong architecture → plan, wrong expression → code.

The core trade-off

Vibe coding optimises for speed; SDD optimises for intent. Neither is always right.

If the intent matters beyond the next prompt, structure wins.

Throwaway script? Vibe away. Production feature a colleague will build on? Write the spec.

Why it caught on

SDD emerged in 2025 and within a year every major AI coding ecosystem shipped its own version. When every vendor independently lands on the same four phases, the pain was real.

Free cheat sheet: the whole method on a few pages — the loop, spec anatomy, EARS, right-sizing — SDD Cheat Sheet.

Go deeper: the full reference — every phase, the tool landscape, three walkthroughs — Spec-Driven Development: The Complete Guide.

How many times have you re-explained the same requirement to an agent in one session? 👇

DEV Community: PromptMaster

5 A2A Mistakes That Break Production Systems

1. Never emitting a terminal state

2. A missing or vague Agent Card

3. Trusting peers by default

4. Confusing A2A with MCP

5. Ignoring long-running work

The meta-pitfall

A production-readiness checklist

Operate agents like services

Frequently asked questions

More in this series

Want to go deeper?

Multi-Agent Orchestration Patterns: Orchestrator, Parallel, and Peer Handoffs

The orchestrator pattern

Sequential vs parallel delegation

Peer delegation and handoffs

Choosing a shape

Patterns compose

Discovery at scale

Three anti-patterns

Cost and latency are real

Keeping orchestration observable

Frequently asked questions

More in this series

Want to go deeper?

Securing Agent-to-Agent Communication: OAuth, JWT, and Zero Trust

Why this stops being optional immediately

How agents authenticate

The three mechanisms

Authenticate proves who; authorize decides what

Zero trust, and why per-session auth isn't enough

Building a trust boundary

Five mistakes that open doors

A security checklist

Design for the agent you cannot see

Frequently asked questions

More in this series

Want to go deeper?

Build Your First A2A Agent in 8 Steps

What you're actually building

Step 1 — Install the SDK

Step 2 — Define your Agent Card

Step 3 — Implement an executor

Step 4 — Wire the request handler and server

Step 5 — Handle the task lifecycle

Step 6 — Enable discovery

Step 7 — Secure the endpoint

Step 8 — Test interoperability

What the SDK handles, and what you own

From hello-world to useful

Frequently asked questions

More in this series

Want to go deeper?

Understanding the A2A Task Lifecycle (and the Bug That Hangs Every Client)

Why A2A models tasks instead of calls

The six states

The four methods you need

input-required is a feature, not an error

The bug that hangs every client

Three ways to track a task

Why an explicit lifecycle pays off

Contexts group related tasks

Frequently asked questions

More in this series

Want to go deeper?

The Agent Card: How AI Agents Discover Each Other

Why discovery has to come first

Where the card lives

What the card contains

A minimal card

Skills are the part that matters most

Public and authenticated cards

Signed cards and trust

Keeping cards current

Discovery at scale

Frequently asked questions

More in this series

Want to go deeper?

What Is the Agent2Agent Protocol? A Complete Introduction to A2A