Dec 8th, 2025: [EN] 🎁 The Twelve Days of A2A: A Christmas Carol for Developers

[Justin_Castilla]

The Twelve Days of A2A: A Christmas Carol for Developers

'Twas the Night Before Deployment...

Picture this, friends: You're sitting by the fireplace, hot cocoa in hand, wondering how to explain agent-to-agent (A2A) protocols to your team. You've got developers who understand MCP servers, they've dabbled in agentic AI, but A2A? That's still wrapped up like a mysterious Christmas present under the tree.

What if I told you that the answer was hiding in plain sight, in a song we've all sung since childhood?

Welcome to The Twelve Days of A2A, where we unwrap agent orchestration using everyone's favorite iterative Christmas carol. Because nothing says "modern distributed systems" quite like partridges, turtle doves, and Elasticsearch.

What's in the Box?

The 12-days-of-a2a project is a very simple but potent demonstration of Google's Agent-to-Agent (A2A) protocol that uses the "Twelve Days of Christmas" as its dataset. Each day of Christmas gets its own specialized agent, all coordinated by a primary orchestrator agent. We've also thrown in integration with Elastic’s new Agent Builder service to show how remote agents can join the holiday party.

Think of it as a proof-of-concept wrapped in tinsel and good cheer.

The Cast of Characters

• 12 Gift Agents: One for each day's gift (partridges, turtle doves, golden rings, etc.)

• 1 Orchestrator Agent: The conductor of our festive agentic symphony

• 1 Elastic Agent: A remote agent in the Elastic Serverless cloud, ready to search for gift information

The beauty here is watching how these agents communicate using a standardized protocol. They're all speaking the same language at the Christmas dinner table—no awkward silences, no confused uncles, just smooth inter-agent collaboration.

Why Should You Care? (Besides the Holiday Spirit)

If you're comfortable with MCP (Model Context Protocol) servers and have been exploring agentic AI, A2A is the natural next step. First, there is a natural inclination for a separation of concerns. Each agent has one job and does it well. Using the 12 Days of Christmas example, the Day 5 agent knows everything about golden rings and nothing about drummers drumming. This is the UNIX philosophy dressed up in a Santa suit.

There is also the lovely gift that keeps on giving: scalability. Want to add a thirteenth day? ("Thirteen Threads a’Thinking"?) Just spin up another agent. The orchestrator doesn't need to care about implementation details. Speaking of not wanting to care about the details, The Elastic agent doesn't run on your machine. It's hosted on Elastic Cloud as a remote service, demonstrating how A2A enables truly distributed agent systems. Your agents can talk to anyone's agents, as long as they speak A2A.This reduces pressure on your metal, and lets others handle that burden.

Lastly Agent Cards (we'll get to these) are like business cards for AI agents. They describe capabilities in a machine-readable format, making discovery and integration automatic. This enforces standardization across all agents that use A2A.

The Architecture: A Christmas Tree of Agents

Let's visualize how this works:

When you ask for information about Day 5's golden rings, the orchestrator:

1. Figures out which gift agent to ask

2. Calls that agent to get base information

3. Optionally reaches out to the Elastic agent for enriched data

4. Combines everything into a festive response

All of this happens through standardized A2A messages. It's like passing notes in class, except the notes are JSON and nobody gets detention.

Agent Cards: The Gift Tags of the A2A World

Every agent in the A2A protocol exposes an "Agent Card": a JSON document that describes what the agent can do. Think of it as a menu at a restaurant or a bio page about their abilities, but for AI capabilities.

Here's what the Day 5 agent's card looks like:

{
  "name": "Day 5 Gift Agent",
  "description": "Provides the gift for day 5 of Christmas: 5 Golden Rings",
  "url": "http://localhost:5005",
  "version": "1.0.0",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "skills": [
    {
      "id": "get_gift",
      "name": "Get Gift",
      "description": "Get the gift for day 5 of Christmas",
      "tags": ["christmas", "gift", "day5"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain"]
    },
    {
      "id": "get_gift_with_elastic",
      "name": "Get Gift with Elastic",
      "description": "Get the gift for day 5 with information from Elastic search",
      "tags": ["christmas", "gift", "elastic", "day5"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain"]
    }
  ]
}

This card tells other agents (and humans) everything they need to know:

• What it does: Handles Day 5 gifts

• How to reach it: http://localhost:5005

• What skills it has: Two skills, one basic, one that integrates with Elastic

• Protocol version: So agents know they're speaking the same dialect

When the orchestrator wants to talk to Day 5's agent, it fetches this card first. It's like checking someone's LinkedIn profile before a meeting—you want to know what they're capable of before you ask them to do something.

The Elastic Connection: When Local Meets Cloud

Here's where things get interesting. Most of our gift agents are local—they run on your machine. But the Elastic agent? That one lives on an Elastic Serverless Cloud Instance. And yet, they all speak the same language. This is thanks to the A2A standardization everyone decided to agree upon.

The Elastic Agent Builder provides a hosted AI agent that can search your Elasticsearch data. Setting it up involves:

1. Creating an Elasticsearch index with Christmas gift data (78 documents, one for each gift occurrence)

2. Configuring an Agent Builder agent that knows how to search that index

3. Selecting any Tools for that Agent Elastic has several, or you can make your own

4. Grabbing the A2A endpoint URL (something like https://your-project.kb.region.elastic.cloud/api/agent_builder/a2a)

Once configured, the local orchestrator can send A2A requests to the remote Elastic agent just as easily as it talks to local agents. The protocol doesn't care where the agent lives.

A Real Request Flow

Let's trace what happens when you run:

$ python main.py --elastic --day 5

Step 1: Orchestrator receives your request

def search_gift_info(self, day: int) -> str:

    gift_info = GIFTS[5]  # {"gift": "Golden Rings", "quantity": 5}

    gift_name = gift_info['gift']

    # Time to call Elastic!

    elastic_info = search_gift(gift_name, day)

Step 2: Fetch the Elastic agent's card

The local wrapper makes an HTTP GET to discover what the remote agent can do:

GET https://your-project.kb.region.elastic.cloud/api/agent_builder/a2a/12_days_agent.json

Authorization: ApiKey <your-es-api-key>

The Elastic agent responds with its Agent Card, revealing skills like:

• platform.core.search - Search Elasticsearch

• platform.core.get_document_by_id - Retrieve specific documents

• platform.core.list_indices - List available indices

• platform.core.execute_esql - Execute an ES|QL query and return the results

Step 3: Send the A2A request

POST https://your-project.kb.region.elastic.cloud/api/agent_builder/a2a/12_days_agent

Content-Type: application/json

Authorization: ApiKey your-es-api-key

And the A2A payload:

{
  "message": {
    "role": "user",
    "content": {
      "type": "text",
      "text": "Find information about Golden Rings from the 12 Days of Christmas, day 5"
    }
  }
}

Step 4: Elastic agent does its magic

Inside Elastic Cloud:

1. Parses the query: "Golden Rings" + "day 5"

2. Searches the christmas-gifts index

3. Finds 5 documents matching those criteria

4. Uses AI to synthesize a rich response from the document contents

5. Packages it in an A2A response

Step 5: Response comes back

{
  "taskId": "elastic_task_67890",
  "status": {
    "state": "COMPLETED"
  },
  "artifacts": [
    {
      "parts": [
        {
          "type": "text",
          "text": "On the fifth day of Christmas, the gift is five golden rings. These rings are perfect circles that symbolize completeness and perfection. The golden material they're made from brings warmth and light during the cold winter season, making them both symbolically and visually significant in the Christmas tradition.\n\nThe five golden rings represent the first five books of the Old Testament: Genesis, Exodus, Leviticus, Numbers, and Deuteronomy, known as the Pentateuch or Torah.\n\nGold rings were among the most valuable gifts one could give, representing wealth, status, and deep affection. Their brilliance and durability made them perfect symbols of lasting love."
        }
      ]
    }
  ]
}

Step 6: Orchestrator combines and presents

Day 5: 5 Golden Rings

Information from Elastic:

On the fifth day of Christmas, the gift is five golden rings. These rings

are perfect circles that symbolize completeness and perfection...

The entire round trip—from your command line to the cloud and back—happens through standardized A2A messages. No custom APIs, no one-off integration code. Just agents talking to agents.

The Three Message Types: A2A's Greatest Hits

A2A communications in this demo boils down to three core patterns:

1. User to Orchestrator

When you run a command, you're sending a simple request:

{
  "message": {
    "role": "user",
    "content": {
      "type": "text",
      "text": "Search for information about day 5 gift with elastic"
    }
  }
}

2. Orchestrator to Gift Agent

The orchestrator asks a specialized agent for help:

{
  "message": {
    "role": "user",
    "content": {
      "type": "text",
      "text": "Get the gift for day 5"
    }
  }
}

The gift agent responds:

{
  "taskId": "task_12345",
  "status": {
    "state": "COMPLETED",
    "message": "Task completed successfully"
  },
  "artifacts": [
    {
      "index": 0,
      "parts": [
        {
          "type": "text",
          "text": "5 Golden Rings"
        }
      ]
    }
  ]
}

3. Orchestrator to Remote Elastic Agent

Same structure, different destination:

{
  "message": {
    "role": "user",
    "content": {
      "type": "text",
      "text": "Find information about Golden Rings from the 12 Days of Christmas, day 5"
    }
  }
}

Notice how the message structure is identical whether you're talking to a local agent or a remote one? That's the power of standardization. The orchestrator doesn't need to know where an agent lives, only what it can do.

What Makes This Special?

Yes, the dataset is festive and fun, but the patterns here apply to any multi-agent system:

Microservices for AI: Each gift agent is like a microservice—small, focused, independently deployable. The orchestrator is your API gateway.

Hybrid Cloud Architectures: Mix local agents (fast, private) with remote agents (powerful, scalable). The A2A protocol makes this seamless.

Discoverable APIs: Agent Cards mean you don't need hand-written documentation. Agents describe themselves.

Language Agnostic: This project is in Python, but A2A is HTTP-based. Your gift agents could be in Python, the orchestrator in Go, and the Elastic agent in whatever Elastic uses (spoiler: probably Java). They don't care.

When you work through this project, you'll have several realizations:

"Wait, it's just HTTP?" - Yes! A2A is built on boring, reliable web standards. No exotic protocols, no proprietary transports.

"The agents don't know about each other?" - Correct! The orchestrator handles routing. Gift agents don't know Elastic exists, and Elastic doesn't know about gift agents. Loose coupling for the win.

"I could replace any of these agents..." - Exactly! Don't like how Day 5's agent works? Swap it out. As long as the new agent speaks A2A and exposes the right skills, the orchestrator won't notice.

"This scales horizontally?" - You bet. Run each gift agent in its own container. Scale the popular ones (everyone wants golden rings). Add load balancers. It's web architecture all the way down.

We're entering an era where AI agents will be as common as web APIs. Just as every company exposes REST APIs today, they'll expose AI agents tomorrow. A2A provides the standardization layer to make this possible.

Imagine your CRM agent talking to your customer's procurement agent to negotiate contract terms. Your monitoring agent can call your cloud provider's incident response agent when things go wrong. Your personal assistant agent books tickets through the theater's reservation agent.

Going Further: Your Next Steps

Extend the Project

• Add a 13th day (Thirteen Threads a’Thinking? Zero Zero-Day Exploits? )

• Integrate a different remote agent (OpenAI? Anthropic? Your own API?)

• Add streaming responses (A2A supports this!)

• Implement state persistence (remember previous queries)

• Add a web UI (Flask + React?)

Apply to Real Problems

• Customer Service: Orchestrator routes queries to specialized agents (billing, technical support, returns)

• Data Analysis: Different agents handle different data sources, orchestrator combines insights

• Content Generation: Writing agent, image agent, SEO agent all coordinate through an orchestrator

• Research: Search multiple databases, synthesize findings, generate reports

Final Thoughts: The Spirit of A2A

The "12 Days of Christmas" is an iterator song—each verse builds on the previous ones. That's exactly what we're doing with A2A. Each agent adds its own gift to the collection, and the orchestrator brings them all together into something greater than the sum of its parts.

In the same way that the carol has been passed down through generations, A2A provides a standard that can be built upon, extended, and improved by the community. We're not building isolated agents anymore—we're building an ecosystem.

So whether you're a developer exploring agentic AI for the first time, an architect designing distributed systems, or just someone who really loves Christmas carols and Python, this project has something for you.

Clone the repo. Run the code. Break things. Fix them. Add your own twist. And maybe, just maybe, you'll find yourself humming "On the fifth day of Christmas, my agent gave to me..." as you architect your next system.

Resources

• Project Repository: github.com/justincastilla/12-days-of-a2a

• Python A2A Library: github.com/themanojdesai/python-a2a

• Google A2A Protocol: google.github.io/A2A

• Elastic Agent Builder: elastic.co/elasticsearch/agent-builder

• Elastic A2A Example: github.com/elastic/elasticsearch-labs

• Building a multi-agent Cluster: https://www.elastic.co/search-labs/blog

Happy Holidays and Happy Coding!

Thank you everyone for joining us in our yearly wrap up of all things merry, bright, and Elastic! May your agents be loosely coupled and your protocols standardized! <3 Justin Castilla