agent_card_test.go

Overview

The agent_card_test.go file contains unit tests designed to validate the behavior of the agent skill building functionality in the system. It primarily tests the generation of agent skill descriptors (a2a.AgentSkill) for a wide variety of agent types, including custom agents, LLM agents with instructions and tools, as well as workflow agents such as loop agents, sequential agents, and parallel agents. The tests ensure that the skill metadata generated matches expected structures, which is crucial for remote agent communication and capability discovery as detailed in Agent Skill Building.

Additionally, the file tests the utility function replacePronouns, which is responsible for converting second-person pronouns in instructions or descriptions into first-person pronouns. This transformation improves the natural language clarity of agent descriptions by making them appear as if the agent is speaking about itself.

The tests are built using Go's testing package and the go-cmp library for deep comparison of complex data structures.

Functions and Methods

must[T agent.Agent](a T, err error) T

• Purpose:
  A helper generic function to simplify test code by panicking immediately if agent creation fails. It unwraps the (agent, error) tuple returned by agent constructors, ensuring tests fail fast on setup errors.

• Parameters:

  • a T: An instance of an agent or sub-agent implementing the agent.Agent interface.

  • err error: The error returned by the agent constructor.

• Returns:

  • T: The agent instance if no error occurred.

• Usage Example:

  agent := must(agent.New(agent.Config{Name: "Test", Description: "Test"}))
  

• Notes:
  This function is used extensively to create agents within test cases without cluttering the tests with error handling.

TestGetAgentSkills_LLMAgent(t *testing.T)

• Purpose:
  Tests the BuildAgentSkills function by verifying that various types of agents produce the correct list of a2a.AgentSkill descriptors. These descriptors include the agent's name, description, ID, and tags that classify the agent type and capabilities.

• Parameters:

  • t *testing.T: The testing context provided by Go's testing framework.

• Test Cases:
  The test function iterates over a slice of structured test cases, each containing:

  • name: A string describing the test scenario.

  • agent: An instance of an agent under test.

  • want: The expected slice of a2a.AgentSkill instances representing the agent's skills.

• Agents Tested Include:

  • Custom agents with only name and description.

  • LLM agents with instructions.

  • LLM agents with integrated tools (geminitool.GoogleSearch and loadartifactstool.New).

  • Empty and populated loop agents (with sub-agents and maximum iteration limits).

  • Empty and populated sequential agents.

  • Empty and populated parallel agents.

  • Deeply nested sub-agents combining loop, sequential, and LLM agents.

• Assertions:
  Uses cmp.Diff to compare the expected and actual skill lists, and fails the test if there is any mismatch, printing a detailed diff.

• Usage Context:
  Validates the correctness of skill metadata generation used to describe agents over the A2A protocol (Remote Agent Communication (A2A)).

TestReplacePronouns(t *testing.T)

• Purpose:
  Verifies the correctness of the replacePronouns function which converts second-person pronouns ("you", "your", "yours", etc.) into first-person equivalents ("I", "my", "mine", etc.) within input strings.

• Parameters:

  • t *testing.T: The testing context.

• Test Cases:
  Includes multiple input strings demonstrating different casing, punctuation, and context scenarios:

  • Mixed-case pronouns ("you", "Your", "YOU").

  • Sentences with no pronouns.

  • Words containing pronoun substrings (e.g., "youth", "yourself") which should not be replaced.

  • Repeated pronouns.

  • Sentences with possessive and contracted forms.

• Assertions:
  Compares the output of replacePronouns to the expected transformed string, failing with a detailed message if there is a mismatch.

Important Implementation Details

• Agent Skill Building Context:
  The tests exercise skill generation logic that inspects agent types and their configurations, including sub-agent orchestration for workflow agents (Agent Workflow Management) and LLM agent properties (LLM Integration and Agents). Skill descriptors include composite descriptions generated by concatenating sub-agent descriptions and pronoun-replaced instructions.

• Pronoun Replacement:
  The replacePronouns function uses case-insensitive matching and careful word boundary checks to avoid altering substrings that look like pronouns but are part of other words. This ensures natural and grammatically correct descriptions.

• Use of Tools in LLM Agents:
  The tests include LLM agents configured with tools like geminitool.GoogleSearch and loadartifactstool.New, demonstrating the ability to generate separate skill entries for each tool integrated into an LLM agent.

• Workflow Agents:
  The test inputs cover loop agents with maximum iterations, unlimited loops, sequential agents, and parallel agents, each producing distinct descriptive skill sets that reflect execution order or concurrency.

• Nested Agent Structures:
  Deeply nested sub-agent scenarios test recursive skill building and naming conventions, ensuring that nested workflows and LLMs are correctly represented in skill metadata.

Interaction with Other Parts of the System

• Agent Skill Building Integration:
  The tested functionality directly supports the generation of agent capabilities advertised in the A2A agent cards, which are used by remote clients and orchestrators to discover and interact with agents (Remote Agent Communication (A2A)).

• Agent Types and Workflow:
  The tests rely on the creation of various agent types from packages related to agent workflows (loopagent, sequentialagent, parallelagent), LLM-based agents (llmagent), and basic custom agents (agent.New), illustrating the interconnectedness with Agent Workflow Management and LLM Integration and Agents.

• Tool Integration:
  The inclusion of tools from geminitool and loadartifactstool shows dependency on the tooling system (Tooling System) and its integration within LLM agents.

• Pronoun Replacement Usage:
  The pronoun replacement function is crucial for producing human-readable skill descriptions from agent instructions, enhancing client-side presentation of agent capabilities.

Visual Diagram: Structure and Workflow of agent_card_test.go

flowchart TD
A[must helper] --> B[TestGetAgentSkills_LLMAgent]
A --> C[TestReplacePronouns]
B --> D[Create Agents]
B --> E[BuildAgentSkills]
B --> F[Compare Skills]
C --> G[replacePronouns]
C --> H[Compare Strings]

• Description:
  This flowchart shows the testing workflow:

  • The must helper is used by both main test functions to instantiate agents safely.

  • TestGetAgentSkills_LLMAgent creates various agent instances, invokes BuildAgentSkills to generate skills, and compares them to expected results.

  • TestReplacePronouns tests the replacePronouns function by comparing transformed strings against expected outputs.

Usage Examples (Extracted from Test Cases)

• Creating a Custom Agent and Testing Skills:

  a := must(agent.New(agent.Config{Name: "Test", Description: "Test test"}))
  skills := BuildAgentSkills(a)
  // skills should contain one custom_agent skill with ID "Test" and description "Test test"
  

• LLM Agent with Instruction:

  a := must(llmagent.New(llmagent.Config{
      Name: "Test LLM",
      Description: "Test llm.",
      Instruction: "You're a helpful agent, only respond with useful information.",
  }))
  skills := BuildAgentSkills(a)
  // skills include a 'model' skill with combined description including the instruction with pronouns replaced
  

• Testing Pronoun Replacement:

  input := "You should do your work and it will be yours."
  output := replacePronouns(input)
  // output == "I should do my work and it will be mine."
  

This file is critical for ensuring that agent skill metadata construction works correctly across a broad spectrum of agent configurations, which in turn supports effective remote agent interaction and discovery in the system.