Designing APIs for humans leads nowhere. What we once considered a best practice is now obsolete. Yes, human developers are good at understanding sometimes ambiguous API documentation. They can write code that handles errors gracefully and makes up for missing explicit data types. Things like strings that can also be null and integers without a maximum are what make human-led API integration interesting. However, most API consumers now aren't human. We're long past those days. Now, AI agents can discover, make requests, and combine API operations, all on their own. But AI agents aren't as resilient to ambiguity as people used to be. That's why they often fail to understand what an API does and how to use operations in more sophisticated workflows. What can you do to reverse this trend and help AI agents succeed? Stay with me to learn more.
This article is brought to you with the help of our supporter, n8n.
n8n is the fastest way to plug AI into your own data. Build autonomous, multi-step agents, using any model, including self-hosted. Use over 400 integrations to build powerful AI-native workflows.
Before trying to find solutions, let’s look at the challenge AI agents face in more detail. You can split the problem into three areas. One area has to do with timeouts related to operations that take too long to complete. This has to do in part with the second group of issues, which have to do with errors that are too generic to understand. And, finally, the biggest challenge, in my opinion, is making inter-API requests work well in a reality where state isn’t easily shared between agents. Timeout challenges happen because traditional synchronous REST operations are blocking. In other words, when you make a request, you have to wait until it ends. If the operation takes too long, AI agents will interpret it as a timeout and will disconnect. In this case, AI agents don’t get an error, but many times when they do, they can’t understand its meaning. Whenever an AI agent uses operation parameters wrongly, or when a payload is malformed, many APIs simply return a generic HTTP 400 error. Because there’s no information about what to fix and how to proceed, AI agents simply give up. And that’s not the only time when they give up. They also do it when they don’t know how to move tasks between different AI agents. Situations that involve workflows with several operations require a heavy handling of context and state, which more often than not tends to fail. There’s a solution, fortunately.
The first step to finding a solution is to introduce a layer of coordination for workflows involving multiple AI agents. This layer of coordination is the A2A (Agent-to-Agent) protocol. You can think of A2A as the system that allows separate agents to talk, delegate work, and hand off tasks across network boundaries. A2A was created by Google and launched in April 2025 in an ecosystem of more than 50 partners, including Atlassian, Box, and Salesforce. Soon after, Google transferred it to the Linux Foundation to establish neutral governance and encourage wide adoption. The primary goals of A2A include the ability to have collaboration between agents built using different technologies, the encapsulation of the complexity each agent has to deal with, and, of course, having a standardized inter-agent communication. While MCP standardizes the way an agent communicates with exposed tools, A2A simplifies the horizontal communication between agents. Both protocols complement each other. Let’s then see how to implement A2A.
The very first thing you need to make A2A work is to have what we call an “agent card.” You can see it as a sort of business card, but for agents, not people. It’s where you advertise what your agent is capable of and how other AI agents can invoke it. Here’s a very simplified example of a card for an agent that handles newsletter subscriptions:
{
"name": "API Changelog Newsletter Agent",
"version": "0.1.0",
"description": "Subscribes readers to the API Changelog newsletter.",
"url": "https://example.com/a2a",
"skills": [
{
"id": "subscribe_api_changelog_newsletter",
"name": "Subscribe to API Changelog newsletter",
"description": "Subscribes an email address to the API Changelog newsletter."
}
]
}By publishing this card at the /.well-known/agent-card.json location, you’re letting other agents know what yours is capable of. There’s more information you can add to the card to help agents interact, such as authentication instructions. This is just an example, so you can see what’s possible. The second thing you want to do is to shift from synchronous operations to an A2A-compliant asynchronous task state machine. That means that, among other things, operations should immediately return a task_id and then let consumers poll for state information. States let consumers understand how far a task is from being completed. An example of a “happy path” is a task that transitions from the submitted state to working and finally to the completed state. Other states include input-required, failed, and canceled. To avoid having to periodically poll to get the latest task state, one good practice is to implement SSE and notify any consumers instantly as states change. And speaking of good practices, there’s one way to avoid failing whenever there’s a bad input. Instead of switching immediately to failed, you can return the input-required state and let the consumer agent ask its human user for help. These initial steps should get you started with the A2A protocol. But there’s more, much more.
While supporting A2A can be interesting, it doesn’t come without a price. Upgrading your API to move away from synchronous operations and support the asynchronous state machine is no piece of cake. If you start thinking about it, your backend must now manage task persistence, state stores, and polling or streaming logic to track long-running operations. Adding to that, you must also handle automated identity verification to make sure you know who’s calling you. In essence, you must pick a robust security framework such as OAuth2 or signed JWT to ensure that agents are verified and can be rate-limited. And the final piece of frustration is related to testing. While procedural synchronous code is easy, testing asynchronous workflows spread across multiple agents and multiple operations isn’t simple.
Knowing all the pros and cons is important. One option you have is to continue as you are and keep your APIs unchanged, targeted at human consumers. If you follow this path, you accept that you’ll gradually become isolated as the rest of the industry moves towards multi-agent ecosystems. The other option is to invest heavily in the engineering effort to make the switch to A2A now. Yes, there’s a cost, and there are associated risks, but the rewards can be even bigger. In the end, it’s your call.
