Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 37

Contracts and Schemas in Agent Interactions

Recommended resources

Hello! Welcome to the final lesson in our module on "Architecting Agentic Systems."

Introduction

In our last lesson, you designed an interaction flow diagram for a multi-agent workflow, orchestrating a team of specialist agents to solve a complex travel booking request. You mapped out what each agent does and the sequence of their collaboration.

However, this raises a crucial question: How do these agents, potentially built by different teams or even different companies, know how to talk to each other? Without clear rules, communication can break down into misunderstandings, errors, or the kind of absurd "digital politeness" that fails to achieve any real goal.

Today, we'll address this by focusing on your final learning outcome for this module: to explain the role of contracts and schemas in governing agent-to-agent interactions. We will explore the "rules of the road" that make robust, multi-agent systems possible.

Look at the diagram below. The "A2A Protocol" arrow represents the structured communication that allows two separate, independent agents to collaborate across boundaries. This lesson is about defining what that arrow actually represents.

Agent-to-Agent Interaction Architectures
This diagram shows two independent agent systems, built with different frameworks. The A2A (Agent-to-Agent) Protocol provides the standardized communication layer that allows them to interact across organizational or technological boundaries.

1. The "Why": The Need for a Common Language

Before we dive into technical specifications, let's understand the problem at a strategic level. When AI agents communicate without a shared understanding of terms, objectives, and rules, they can fail in unexpected ways. They might agree with each other endlessly to be "helpful," abandoning their original goals.

This isn't just a theoretical problem. Let's read a brief article from Salesforce AI Research that illustrates this challenge with a vivid example and introduces the solution: a "semantic layer" that acts as a diplomatic protocol for machines.

The A2A Semantic Layer: Building Trust into Agent-to ... - Salesforce

This article, 'The A2A Semantic Layer: Building Trust into Agent-to-Agent Interaction', highlights the risks of unstructured agent communication and makes the case for standardized schemas.

Please read the following two parts: Start from the beginning and read down to the section titled 'Building on Protocol Foundations'. Pay close attention to the shoe return example and the 'echoing' phenomenon. Then, read the section titled '2: The Standard Language Challenge' and its solution, 'Domain-Expert Communication Schemas'. Focus on why unstructured 'natural language' chat between agents is problematic and how standardized schemas provide a solution.

As the article argues, the solution is not just better AI models, but a better architecture built on structured communication. This is where contracts and schemas become essential. They provide a precise, unambiguous "dictionary" that agents can use to negotiate and collaborate effectively.

2. The "What": The A2A Protocol and the Agent Card

Now that we've established the need for a common language, let's examine a real-world implementation: the Agent-to-Agent (A2A) Protocol. This open standard, initially developed by Google and now part of the Linux Foundation, is designed to solve this exact problem.

The following video from IBM Technology provides a clear and concise overview of how the A2A protocol works. It introduces the most important component for our lesson: the Agent Card.

A2A Protocol (Agent2Agent) Explained: How AI Agents Collaborate

This video, 'A2A Protocol (Agent2Agent) Explained', will introduce you to the core concepts of how A2A governs agent discovery, authentication, and communication.

Watch from the beginning to 06:28. Pay special attention to the three stages: Discovery: How a client agent finds a remote agent and learns its capabilities through the 'Agent Card'. Authentication: How the Agent Card specifies security requirements. Communication: How the agents exchange tasks and results using a standard format (JSON-RPC).

The video introduces the Agent Card as the centerpiece of discovery. It's a JSON metadata document that an agent publishes to advertise its identity, skills, and communication rules. In essence, the Agent Card is the contract.

3. Deep Dive: Anatomy of a Schema

Let's dissect this contract. The Agent Card is a concrete example of a schema that governs agent interactions. The detailed article below breaks down its structure, showing how it formalizes the concepts you've already learned about, like capability manifests.

A2A Protocol explained: How AI agents communicate across systems

The article 'A2A Protocol explained: How AI agents communicate across systems' provides a detailed breakdown of the Agent Card schema. This will give you a practical understanding of what an agent contract looks like.

Please read the following three sections, focusing on the example JSON snippets: 'Agent card: How A2A enables discovery and capability advertising': This shows the overall structure, defining the agent's identity and endpoints. 'Defining agent capabilities and skills in A2A protocol': Notice how the skills array is a formalized, discoverable version of the capability manifests we discussed previously. 'A2A security: OAuth2, API keys, and enterprise authentication': This shows how security requirements are also part of the discoverable contract. As you read, think of this as the 'API documentation' for an AI agent.

This structured Agent Card ensures there is no ambiguity. A client agent doesn't have to guess what a "NetOps Agent" can do; it can read the skills section and see clearly defined capabilities like detect-network-incident and triage-incident. This machine-readable contract is the foundation of reliable automation.

4. Schemas for Tasks and Results

The contract doesn't stop at discovery. It also defines the schema for the entire communication lifecycle, including how tasks are requested and how results are returned.

This is critical from a UX and architectural perspective. If an agent returns a structured result, you can design a rich UI component to display it. If it returns an unstructured text blob, your options are far more limited.

Let's look at how A2A handles this.

A2A Protocol explained: How AI agents communicate across systems

We'll continue with the same Codilime article to see how A2A defines schemas for requests and responses.

Read the following two sections: 'A2A task lifecycle: From submission to completion': Look at the message/send request example. Note how it's a standard JSON-RPC request with structured parts. 'A2A artifacts: Returning structured data, files, and multi-part results': This is key. See how the response Artifact is not just text, but a structured object containing TextPart, DataPart, and FilePart. This ensures the result is machine-consumable.

By enforcing a schema on both the request (message/send) and the response (Artifact), the A2A protocol ensures that the entire conversation is predictable and reliable.

5. Your Turn: Applying Contracts to the Travel Planner

Let's revisit the travel booking scenario from our last lesson. You designed an orchestration flow with a TravelPlannerAgent (the coordinator) that delegates tasks to a FlightSearchAgent and a HotelSearchAgent.

Your Task:
Imagine you are the architect for the TravelPlannerAgent. Before you can use the FlightSearchAgent and HotelSearchAgent, you must inspect their Agent Cards to ensure they are trustworthy and compatible.

Based on what you've learned, list at least five key fields or sections you would need to find in their Agent Cards and briefly explain why each one is critical for your TravelPlannerAgent to do its job.

Click to see a possible solution and explanation

Here are some of the most critical elements you'd look for in the Agent Cards of the FlightSearchAgent and HotelSearchAgent:

  1. provider: This tells you who built and operates the agent (e.g., "Google Flights," "Booking.com"). This is essential for establishing trust and accountability. Is this a reputable source?

  2. supportedInterfaces: This provides the actual URL endpoint for the agent. Without this, your TravelPlannerAgent wouldn't know where to send its requests.

  3. skills: This is the core of the capability contract. You would look for a skill with an id like find_flights or find_hotels. The description and examples would confirm that the skill does what you expect.

  4. inputModes / outputModes for the skill: You need to verify that the skill accepts structured data (e.g., application/json) for the query and, crucially, returns structured data for the results. If it only returns text/plain, your planner can't reliably parse the flight options to validate them.

  5. securitySchemes / security: This section tells you how to authenticate. Does it require an API key? An OAuth2 token? Your TravelPlannerAgent must be able to meet these requirements to gain access.

  6. (Advanced) A schema for skill parameters: While not fully standardized in A2A yet (as noted in the Codilime article's "gaps" section), you would hope to find documentation or an extension defining the exact JSON schema for the find_flights skill's input (e.g., { "origin": "string", "destination": "string", "departure_date": "YYYY-MM-DD" }) and its output. This removes all guesswork and makes the integration far more robust.

Conclusion

Congratulations on completing the "Architecting Agentic Systems" module! You've gone from understanding single agent capabilities to designing and defining the rules for complex, multi-agent collaborations.

Key Takeaways:

  • Contracts Prevent Chaos: Agent-to-agent communication requires structured contracts and schemas to be reliable, trustworthy, and effective. Unstructured communication leads to unpredictable failures.
  • The Agent Card is the Contract: In the A2A protocol, the Agent Card serves as a machine-readable contract, advertising an agent's identity, capabilities (skills), endpoints, and security rules.
  • Schemas Govern the Full Lifecycle: Effective contracts define the schema for not only discovery but also for task requests (e.g., JSON-RPC) and structured results (Artifacts), ensuring the entire interaction is predictable.
  • Architecture is About Definition: As an architect, your role is to define these contracts, ensuring that all agents in your system—whether you build them or not—can communicate clearly and reliably.

Next Steps

You now have a solid foundation in designing the technical architecture of agentic systems. However, a brilliant architecture is only valuable if it's economically sustainable. In our next module, "AI Economics & Cost Optimization," we will shift our focus to the business and financial side of these systems. We'll begin by exploring the fundamental drivers of cost for Large Language Models, as you learn to explain how token-based pricing and context window size impact LLM inference costs.