a2a_test.go

Overview

The a2a_test.go file contains automated tests that verify the functionality of the Agent-to-Agent (A2A) communication protocol within the system. Specifically, it tests the integration of the web launcher serving the A2A protocol, ensuring that agents exposed via HTTP endpoints can be invoked correctly and respond as expected.

This file sets up a minimal web server environment that launches an A2A agent and then uses an A2A client to send messages to that agent, validating the full request-response cycle. The tests ensure that:

• A free TCP port can be acquired for running the server.

• The web launcher correctly parses command-line arguments and starts serving the A2A endpoint.

• An agent can be instantiated with a simple behavior (responding "Hello, world!").

• The client can resolve the agent’s card via HTTP and send a message, receiving the expected response artifact.

This file exercises components related to distributed agent communication, session management, and web server launch logic, relying heavily on the A2A protocol and launcher infrastructure.

Functions

getFreePort(t *testing.T) int

• Purpose:
  Obtains a free TCP port on the localhost interface by temporarily opening a TCP listener on port 0 (which instructs the OS to allocate an available port) and then closing it immediately. This port number is returned for use in tests requiring a free port.

• Parameters:

  • t *testing.T: The test context, used to report fatal errors if port acquisition fails.

• Returns:

  • int: The acquired free port number.

• Usage:
  Used in tests to avoid port conflicts when starting local servers.

• Implementation Details:
  The function resolves the TCP address for "localhost:0", listens on it, extracts the port from the bound address, closes the listener, and returns the port. It uses fatal test failures if any step fails.

TestWebLauncher_ServesA2A(t *testing.T)

• Purpose:
  End-to-end test that verifies the web launcher can serve an agent exposed via A2A over HTTP, and that messages sent by an A2A client receive the correct response.

• Parameters:

  • t *testing.T: The test context.

• Returns:
  None (test function).

• Description / Workflow:

  1. Context and Port Setup:
     Obtains a background context from the test and uses getFreePort to select a free port for the web server.

  2. Web Launcher Initialization:
     Creates a new web launcher instance wrapping the A2A launcher. Parses command-line arguments to specify the port and agent URL.

  3. Agent Definition:
     Defines a simple agent named "HelloWorldAgent" using agent.New. This agent’s run function yields a single event containing a text message "Hello, world!". It uses the genai package to create the content.

  4. Launcher Configuration:
     Configures the launcher with an AgentLoader that loads the single agent and an in-memory session service (session.InMemoryService).

  5. Server Start:
     Runs the launcher in a separate goroutine, serving the A2A endpoint on the selected port.

  6. Agent Card Resolution:
     Uses agentcard.DefaultResolver to resolve the agent’s card (metadata) from the running server URL. Retries up to 3 times with brief delays to allow server startup.

  7. Client Initialization:
     Creates an A2A client from the resolved agent card.

  8. Sending Message and Validation:
     Sends a user message "Hi!" to the agent via client.SendMessage. Expects a returned task with exactly one artifact containing one text part matching the "Hello, world!" message produced by the agent.

• Error Handling:
  Fatal errors are triggered if any step of setup, communication, or validation fails.

• Usage Example:
  Run as part of the test suite to ensure that web-launcher-based A2A agents serve and respond correctly.

Important Implementation Details

• The test leverages the web.NewLauncher from REST API and Web Launchers and the A2A protocol components from Remote Agent Communication (A2A).

• The agent uses the agent.New interface from AI Agent Framework with a simple run function that yields a single event containing a text response.

• The test uses an in-memory session service (session.InMemoryService) from Session Management to avoid persistence complexity.

• The agent card resolution and client creation ensure that the test simulates real-world remote agent discovery and communication.

• Concurrency is managed by running the server in a goroutine, and synchronization is handled via retries with sleeps to wait for server readiness.

• The test asserts the integrity of the returned data types and contents, verifying the structure of artifacts and parts as defined in Artifact Management.

Interactions with Other Parts of the System

• Launcher System:
  Uses the launcher and web launcher components (launcher, web) to start HTTP servers exposing A2A agents.

• Agent Framework:
  Defines agents, their lifecycle, and invocation context via the agent package.

• Session Service:
  Uses in-memory session storage to manage interaction state during tests.

• A2A Protocol:
  Employs A2A client and agent card resolution from the a2aclient and agentcard packages to perform remote communication.

• Networking:
  Uses Go networking primitives (net) to find free TCP ports dynamically to avoid conflicts during testing.

• GenAI Content:
  Uses the genai package to create structured content for agent events.

This file effectively tests the integration of these components in a minimal but realistic scenario.

Diagram: Function Flow and Component Interactions in a2a_test.go

flowchart TD
A[getFreePort] --> B[TestWebLauncher_ServesA2A]
B --> C[Create Web Launcher]
C --> D[Parse CLI Args]
D --> E[Define Agent with agent.New]
E --> F[Configure Launcher]
F --> G["Run Launcher Server (goroutine)"]
G --> H["Resolve Agent Card (agentcard.DefaultResolver)"]
H --> I[Create A2A Client from Card]
I --> J[Send Message to Agent]
J --> K[Receive Task Response]
K --> L[Validate Response Content]

• getFreePort is called first to reserve an available TCP port.

• TestWebLauncher_ServesA2A orchestrates creating the launcher, agent, and client.

• The launcher server runs asynchronously.

• Agent card resolution enables the client to connect.

• Client sends a message and receives a response task.

• The test validates the response's artifact contents.

Detailed Explanation of Key Packages and Types Used

• web.Launcher: Implements a web server launcher that serves sublaunchers including A2A agents using HTTP. Part of REST API and Web Launchers.

• agent.New: Creates an AI agent with specified configuration including a Run function that defines agent behavior during invocation. Part of AI Agent Framework.

• session.InMemoryService: Provides an in-memory session store for testing and transient use, aligned with Session Management.

• agentcard.DefaultResolver: Resolves agent cards (metadata describing remote agents accessible over HTTP endpoints) per Remote Agent Communication (A2A).

• a2aclient.NewFromCard: Creates an A2A client that can send messages to remote agents based on their resolved cards.

• a2acore.MessageSendParams and a2acore.Message: Structures defining message parameters and message content for A2A communication.

• session.Event and genai.Content: Define the event and content structures for agent invocation results.

Usage Notes

• The test depends on network availability of localhost and the ability to open TCP listeners.

• It requires that the imported packages are correctly implemented and linked.

• The TestWebLauncher_ServesA2A test is a system integration test covering multiple layers: network, agent lifecycle, session, and client-server communication.

• The getFreePort utility function ensures tests do not fail due to port conflicts by dynamically selecting ports.

References

For deeper understanding of concepts and components used in this file, see the following topics:

• Remote Agent Communication (A2A)

• REST API and Web Launchers

• AI Agent Framework

• Session Management

• Artifact Management