agent_card.go

Overview

The agent_card.go file is responsible for generating descriptive skill metadata about agents in the system. It builds a list of a2a.AgentSkill objects that summarize an agent's capabilities, including its core model or workflow type, integrated tools, and sub-agent compositions. This metadata is used in the Agent-To-Agent (A2A) protocol's AgentCard to inform clients about what an agent can do, facilitating discovery, orchestration, and delegation in distributed multi-agent systems.

The file covers:

• Skill extraction for LLM-based agents and non-LLM agents (e.g., workflow agents).

• Recursive skill building for sub-agents.

• Natural language descriptions generated from agent instructions and configuration.

• Pronoun and verb conjugation adjustments to improve human-readable descriptions.

• Tagging skills by agent type to aid in categorization.

These capabilities help remote clients understand agent features before invoking them and support detailed agent capability advertisements.

Classes and Functions

BuildAgentSkills(agent.Agent) []a2a.AgentSkill

Purpose:
Entry point function that builds a comprehensive list of a2a.AgentSkill descriptors for a given agent. It combines primary skills with recursively collected sub-agent skills.

Parameters:

• agent.Agent: The agent instance for which to build skill metadata.

Returns:

• []a2a.AgentSkill: A slice of agent skills describing the agent's capabilities.

Usage Example:

skills := BuildAgentSkills(myAgent)
for _, skill := range skills {
    fmt.Println(skill.Name, ":", skill.Description)
}

buildPrimarySkills(agent.Agent) []a2a.AgentSkill

Purpose:
Determines whether the agent is an LLM-based agent or not and delegates to the appropriate skill building function.

Parameters:

• agent.Agent: The agent instance.

Returns:

• []a2a.AgentSkill: Primary skills of the agent.

buildSubAgentSkills(agent.Agent) []a2a.AgentSkill

Purpose:
Recursively builds skills for all sub-agents of the given agent. Each sub-agent skill is prefixed with the sub-agent's name and tagged as a sub-agent skill.

Parameters:

• agent.Agent: The parent agent.

Returns:

• []a2a.AgentSkill: Skills collected from sub-agents with hierarchical naming.

buildLLMAgentSkills(agent.Agent, *llminternal.State) []a2a.AgentSkill

Purpose:
Constructs skill descriptors for LLM-based agents. It includes:

• A primary skill representing the LLM model and instructions.

• Additional skills for each tool integrated into the LLM agent.

Parameters:

• agent.Agent: The LLM agent.

• *llminternal.State: Internal LLM agent state revealing tools and instructions.

Returns:

• []a2a.AgentSkill: Skills representing the LLM model and its tools.

buildNonLLMAgentSkills(agent.Agent) []a2a.AgentSkill

Purpose:
Builds skills for non-LLM agents such as workflow agents and custom agents. It also describes orchestration when sub-agents are present.

Parameters:

• agent.Agent: The agent instance.

Returns:

• []a2a.AgentSkill: Skills describing the agent and its sub-agent orchestration.

buildAgentDescription(agent.Agent, *iagent.State) string

Purpose:
Generates a natural language description of the agent, factoring in:

• The agent's self-description.

• Descriptions of sub-agents based on workflow type.

• Default descriptions when no other text is available.

Parameters:

• agent.Agent: The agent instance.

• *iagent.State: Internal agent state revealing type and configuration.

Returns:

• string: A descriptive summary of the agent's behavior.

buildSequentialAgentDescription(agent.Agent) string

Purpose:
Creates a narrative description for sequential workflow agents by enumerating sub-agents in execution order (first, then, finally).

buildParallelAgentDescription(agent.Agent) string

Purpose:
Creates a natural language description for parallel workflow agents, describing concurrent execution of sub-agents.

buildLoopAgentDescription(agent.Agent, *iagent.State) string

Purpose:
Generates a description for loop workflow agents, including the maximum number of iterations and sub-agent execution details.

buildDescriptionFromInstructions(agent.Agent, *llminternal.State) string

Purpose:
Builds descriptions for LLM agents from instructions and global instructions, replacing pronouns to convert second-person instructions into first-person perspective for clarity.

replacePronouns(string) string

Purpose:
Replaces second-person pronouns and verb conjugations in instructions to first-person equivalents to improve agent self-descriptions.

Example:

• "You are" → "I am"

• "Your" → "My"

getDefaultAgentDescription(*iagent.State) string

Purpose:
Returns a default description string based on the internal agent type if no custom descriptions are available.

getAgentTypeTag(*iagent.State) string

Purpose:
Returns a string tag identifying the agent type, such as "llm_agent" or "sequential_workflow", used for skill tagging.

getAgentSkillName(*iagent.State) string

Purpose:
Determines the skill name used for the primary agent skill, typically "model" for LLM agents or "workflow" for workflow agents.

getInternalState(agent.Agent) *iagent.State

Purpose:
Extracts the internal agent state from an agent.Agent interface if it implements the internal agent interface. Otherwise, returns a default custom agent state.

isWorkflowAgent(*iagent.State) bool

Purpose:
Checks if the agent type corresponds to a workflow agent type (loop, sequential, or parallel).

Important Implementation Details and Algorithms

• Recursive Skill Gathering:
  The function buildSubAgentSkills traverses sub-agents recursively to produce hierarchical skill sets that include sub-agent names in IDs and names, enabling clear identification of nested capabilities.

• Pronoun Replacement:
  The function replacePronouns uses regex patterns to replace second-person pronouns with first-person, which is essential for making LLM-generated instructions sound natural when presented as agent self-descriptions.

• Workflow Descriptions:
  The descriptive functions for sequential, parallel, and loop agents use positional logic (e.g., first, then, finally) to generate coherent natural language explanations of the agent's sub-agent orchestration.

• Tagging Strategy:
  Skills are tagged by agent type and role (e.g., "llm", "tools", "orchestration") to allow downstream clients or UI components to filter or group capabilities effectively.

Interaction with Other System Components

• This file is part of the Remote Agent Communication (A2A) module, providing the skill metadata that populates a2a.AgentCard structures used by remote clients to discover and understand agent capabilities.

• It interacts with internal agent state representations (iagent.State) and LLM-specific internal states (llminternal.State) by calling internal reveal functions to access configuration details.

• The skills generated here inform clients and orchestrators about what the agent or its sub-agents can do, complementing the dynamic runtime interactions managed by:

  • A2A Agent Implementation for communication and invocation.

  • Event Conversion and Processing for translating events.

  • Executor and Server components that run agents in response to requests.

• It enhances Agent Workflow Management by clarifying the roles and execution order of workflow agents and their sub-agents.

Diagram: Agent Skill Building Structure

flowchart TD
Agent[Agent Instance]
BuildSkills(BuildAgentSkills)
PrimarySkills[buildPrimarySkills]
SubAgentSkills[buildSubAgentSkills]
LLMSkills[buildLLMAgentSkills]
NonLLMSkills[buildNonLLMAgentSkills]
SkillList[""["] a2a.AgentSkill"]
Agent --> BuildSkills
BuildSkills --> PrimarySkills
BuildSkills --> SubAgentSkills
PrimarySkills -->|LLM Agent| LLMSkills
PrimarySkills -->|Non-LLM Agent| NonLLMSkills
LLMSkills --> SkillList
NonLLMSkills --> SkillList
SubAgentSkills --> SkillList

This flowchart illustrates the sequence of steps starting from an agent instance, where primary skills are built based on agent type, sub-agent skills are recursively collected, and all are combined into the final list of a2a.AgentSkill objects.

References to Relevant Topics

• The skill building here is a key component in the Remote Agent Communication (A2A) system, particularly the subtopic Agent Skill Building, which outlines the rationale and usage of skill metadata in agent cards.

• For details on how the agent cards and skills are consumed in network communication and remote invocation, see the A2A Agent Implementation and Executor and Server topics.

• The internal agent state and LLM instruction details referenced here relate to the LLM Integration and Agents and Agent Workflow Management topics, which define agent configurations and workflows.

• Pronoun replacement and instruction processing are conceptually linked to Instruction Template Processing and Instruction Injection, which handle dynamic prompt generation and text processing for LLMs.

This documentation details the mechanisms for generating agent skill descriptions that enable comprehensive capability advertisement in distributed multi-agent systems.