Connect to remote agents with A2A protocol

In this exercise, you’ll use Azure AI Agent Service with the A2A protocol to create simple remote agents that interact with one another. These agents will assist technical writers with preparing their developer blog posts. A title agent will generate a headline, and an outline agent will use the title to develop a concise outline for the article. Let’s get started

Tip: The code used in this exercise is based on the for Microsoft Foundry SDK for Python. You can develop similar solutions using the SDKs for Microsoft .NET, JavaScript, and Java. Refer to Microsoft Foundry SDK client libraries for details.

This exercise should take approximately 30 minutes to complete.

Note: Some of the technologies used in this exercise are in preview or in active development. You may experience some unexpected behavior, warnings, or errors.

Prerequisites

Before starting this exercise, ensure you have:

Visual Studio Code installed
An active Azure subscription
Python version 3.10 or higher installed

Install the Microsoft Foundry VS Code extension

Let’s start by installing and setting up the VS Code extension.

Open Visual Studio Code.
Select Extensions from the left pane (or press Ctrl+Shift+X).
In the search bar, type Microsoft Foundry and press Enter.
Select the Microsoft Foundry extension from Microsoft and click Install.
After installation is complete, verify the extension appears in the primary navigation bar on the left side of Visual Studio Code.

Now you’ll connect to your Azure resources and create a new AI Foundry project.

In the VS Code sidebar, select the Microsoft Foundry extension icon.
In the Resources view, select Sign in to Azure… and follow the authentication prompts.

Note: You won’t see this option if you’re already signed in.
Create a new Foundry project by selecting the + (plus) icon next to Resources in the Foundry Extension view.
Select your Azure subscription from the dropdown.
Choose whether to create a new resource group or use an existing one:

To create a new resource group:
- Select Create new resource group and press Enter
- Enter a name for your resource group (e.g., “rg-ai-agents-lab”) and press Enter
- Select a location from the available options and press Enter
To use an existing resource group:
- Select the resource group you want to use from the list and press Enter
Enter a name for your Foundry project (e.g., “ai-agents-project”) in the textbox and press Enter.
Wait for the project deployment to complete. A popup will appear with the message “Project deployed successfully.”

Deploy a model

In this task, you’ll deploy a model from the Model Catalog to use with your agent.

When the “Project deployed successfully” popup appears, select the Deploy a model button. This opens the Model Catalog.

Tip: You can also access the Model Catalog by selecting the + icon next to Models in the Resources section, or by pressing F1 and running the command Microsoft Foundry: Open Model Catalog.
In the Model Catalog, locate the gpt-4.1 model (you can use the search bar to find it quickly).
Select Deploy next to the gpt-4.1 model.
Configure the deployment settings:
- Deployment name: Enter a name like “gpt-4.1”
- Deployment type: Select Global Standard (or Standard if Global Standard is not available)
- Model version: Leave as default
- Tokens per minute: Leave as default
Select Deploy in Microsoft Foundry in the bottom-left corner.
In the confirmation dialog, select Deploy to deploy the model.
Wait for the deployment to complete. Your deployed model will appear under the Models section in the Resources view.
Right-click the name project deployment and select Copy Project Endpoint. You’ll need this URL to connect your agent to the Foundry project in the next steps.

Clone the starter code repository

For this exercise, you’ll use starter code that will help you connect to your Foundry project and create an agent that can process expenses data. You’ll clone this code from a GitHub repository.

Navigate to the Welcome tab in VS Code (you can open it by selecting Help > Welcome from the menu bar).
Select Clone git repository and enter the URL of the starter code repository: https://github.com/MicrosoftLearning/mslearn-ai-agents.git
Create a new folder and choose Select as Repository Destination, then open the cloned repository when prompted.
In the Explorer view, navigate to the Labfiles/06-build-remote-agents-with-a2a/Python folder to find the starter code for this exercise.

The provided files include:
```
 python
 ├── outline_agent/
 │   ├── agent.py
 │   ├── agent_executor.py
 │   └── server.py
 ├── routing_agent/
 │   ├── agent.py
 │   └── server.py
 ├── title_agent/
 │   ├── agent.py
 |   ├── agent_executor.py
 │   └── server.py
 ├── client.py
 └── run_all.py
```
Each agent folder contains the Azure AI agent code and a server to host the agent. The routing agent is responsible for discovering and communicating with the title and outline agents. The client allows users to submit prompts to the routing agent. run_all.py launches all the servers and runs the client.
Right-click on the requirements.txt file and select Open in Integrated Terminal.
In the terminal, enter the following command to install the required Python packages in a virtual environment:
```
 python -m venv labenv
 .\labenv\Scripts\Activate.ps1
 pip install -r requirements.txt
```
Open the .env file, replace the your_project_endpoint placeholder with the endpoint for your project (copied from the project deployment resource in the Microsoft Foundry extension) and ensure that the MODEL_DEPLOYMENT_NAME variable is set to your model deployment name. Use Ctrl+S to save the file after making these changes.

Create an A2A application

Now you’re ready to create a client app that uses an agent. Some code has been provided for you in a GitHub repository.

Create a discoverable agent

In this task, you create the title agent that helps writers create trendy headlines for their articles. You also define the agent’s skills and card required by the A2A protocol to make the agent discoverable.

Tip: As you add code, be sure to maintain the correct indentation. Use the existing comments as a guide, entering the new code at the same level of indentation.

Open the title_agent/agent.py file in the code editor.

Find the comment Create the agents client and add the following code to connect to the Azure AI project:

Tip: Be careful to maintain the correct indentation level.

# Create the agents client
self.client = AgentsClient(
    endpoint=os.environ['PROJECT_ENDPOINT'],
    credential=DefaultAzureCredential(
        exclude_environment_credential=True,
        exclude_managed_identity_credential=True
    )
)

Find the comment Create the title agent and add the following code to create the agent:

# Create the title agent
self.agent = self.client.create_agent(
    model=os.environ['MODEL_DEPLOYMENT_NAME'],
    name='title-agent',
    instructions="""
    You are a helpful writing assistant.
    Given a topic the user wants to write about, suggest a single clear and catchy blog post title.
    """,
)

Find the comment Create a thread for the chat session and add the following code to create the chat thread:
```
# Create a thread for the chat session
thread = self.client.threads.create()
```

Locate the comment Send user message and add this code to submit the user’s prompt:

# Send user message
self.client.messages.create(thread_id=thread.id, role=MessageRole.USER, content=user_message)

Under the comment Create and run the agent, add the following code to initiate the agent’s response generation:
```
# Create and run the agent
run = self.client.runs.create_and_process(thread_id=thread.id, agent_id=self.agent.id)
```
The code provided in the rest of the file will process and return the agent’s response.
Save the code file (CTRL+S). Now you’re ready to share the agent’s skills and card with the A2A protocol.
Open the title_agent/server.py file in the code editor.

Find the comment Define agent skills and add the following code to specify the agent’s functionality:

# Define agent skills
skills = [
    AgentSkill(
        id='generate_blog_title',
        name='Generate Blog Title',
        description='Generates a blog title based on a topic',
        tags=['title'],
        examples=[
            'Can you give me a title for this article?',
        ],
    ),
]

Find the comment Create agent card and add this code to define the metadata that makes the agent discoverable:

# Create agent card
agent_card = AgentCard(
    name='AI Foundry Title Agent',
    description='An intelligent title generator agent powered by Foundry. '
    'I can help you generate catchy titles for your articles.',
    url=f'http://{host}:{port}/',
    version='1.0.0',
    default_input_modes=['text'],
    default_output_modes=['text'],
    capabilities=AgentCapabilities(),
    skills=skills,
)

Locate the comment Create agent executor and add the following code to initialize the agent executor using the agent card:
```
# Create agent executor
agent_executor = create_foundry_agent_executor(agent_card)
```
The agent executor will act as a wrapper for the title agent you created.

Find the comment Create request handler and add the following to handle incoming requests using the executor:

# Create request handler
request_handler = DefaultRequestHandler(
    agent_executor=agent_executor, task_store=InMemoryTaskStore()
)

Under the comment Create A2A application, add this code to create the A2A-compatible application instance:
```
# Create A2A application
a2a_app = A2AStarletteApplication(
    agent_card=agent_card, http_handler=request_handler
)
```
This code creates an A2A server that will share the title agent’s information and handle incoming requests for this agent using the title agent executor.
Save the code file (CTRL+S) when you have finished.

Enable messages between the agents

In this task, you use the A2A protocol to enable the routing agent to send messages to the other agents. You also allow the title agent to receive messages by implementing the agent executor class.

Open the routing_agent/agent.py file in the code editor.

The routing agent acts as an orchestrator that handles user messages and determines which remote agent should process the request.

When a user message is received, the routing agent:
- Starts a conversation thread.
- Uses the create_and_process method to evaluate the best-matching agent for the user’s message.
- The message is routed to the appropriate agent over HTTP using the send_message function.
- The remote agent processes the message and returns a response.
The routing agent finally captures the response and returns it to the user through the thread.

Notice that the send_message method is async and must be awaited for the agent run to complete successfully.

Add the following code under the comment Retrieve the remote agent’s A2A client using the agent name:

# Retrieve the remote agent's A2A client using the agent name 
client = self.remote_agent_connections[agent_name]

Locate the comment Construct the payload to send to the remote agent and add the following code:

# Construct the payload to send to the remote agent
payload: dict[str, Any] = {
    'message': {
        'role': 'user',
        'parts': [{'kind': 'text', 'text': task}],
        'messageId': message_id,
    },
}

Find the comment Wrap the payload in a SendMessageRequest object and add the following code:

# Wrap the payload in a SendMessageRequest object
message_request = SendMessageRequest(id=message_id, params=MessageSendParams.model_validate(payload))

Add the following code under the comment Send the message to the remote agent client and await the response:

# Send the message to the remote agent client and await the response
send_response: SendMessageResponse = await client.send_message(message_request=message_request)

Save the code file (CTRL+S) when you have finished. Now the routing agent is able to discover and send messages to the title agent. Let’s create the agent executor code to handle those incoming messages from the routing agent.
Open the title_agent/agent_executor.py file in the code editor.

The AgentExecutor class implemenation must contain the methods execute and cancel. The cancel method has been provided for you. The execute method includes a TaskUpdater object that manages events and signals to the caller when the task is complete. Let’s add the logic for task execution.

In the execute method, add the following code under the comment Process the request:

# Process the request
await self._process_request(context.message.parts, context.context_id, updater)

In the _process_request method, add the following code under the comment Get the title agent:
```
# Get the title agent
agent = await self._get_or_create_agent()
```

Add the following code under the comment Update the task status:

# Update the task status
await task_updater.update_status(
    TaskState.working,
    message=new_agent_text_message('Title Agent is processing your request...', context_id=context_id),
)

Find the comment Run the agent conversation and add the following code:

# Run the agent conversation
responses = await agent.run_conversation(user_message)

Find the comment Update the task with the responses and add the following code:

# Update the task with the responses
for response in responses:
    await task_updater.update_status(
        TaskState.working,
        message=new_agent_text_message(response, context_id=context_id),
    )

Find the comment Mark the task as complete and add the following code:

# Mark the task as complete
final_message = responses[-1] if responses else 'Task completed.'
await task_updater.complete(
    message=new_agent_text_message(final_message, context_id=context_id)
)

Now your title agent has been wrapped with an agent executor that the A2A protocol will use to handle messages. Great work!

Run the application

In the integrated terminal, enter the following command to run the application:
```
 python run_all.py
```
The application runs using the credentials for your authenticated Azure session to connect to your project and create and run the agent. You should see some output from each server as it starts.
Wait until the prompt for input appears, then enter a prompt such as:
```
Create a title and outline for an article about React programming.
```
After a few moments, you should see a response from the agent with the results.
Enter quit to exit the program and stop the servers.

You can also use deactivate to exit the Python virtual environment in the terminal.

Summary

In this exercise, you used the Azure AI Agent Service SDK and the A2A Python SDK to create a remote multi-agent solution. You created a discoverable A2A-compatible agent and set up a routing agent to access the agent’s skills. You also implemented an agent executor to process incoming A2A messages and manage tasks. Great work!

Clean up

If you’ve finished exploring Azure AI Agent Service, you should delete the resources you have created in this exercise to avoid incurring unnecessary Azure costs.

Return to the browser tab containing the Azure portal (or re-open the Azure portal at https://portal.azure.com in a new browser tab) and view the contents of the resource group where you deployed the resources used in this exercise.
On the toolbar, select Delete resource group.
Enter the resource group name and confirm that you want to delete it.