Enriching A2A Agent Cards

This guide explains how to use mav-agent-config.yaml to enhance your agent's A2A Agent Card with additional metadata for discovery and interoperability.

Overview

When AgentVisor exposes your agents via the A2A Transport, it generates an Agent Card that other A2A clients use for discovery. By default, this card contains basic information from your LangGraph schemas.

The optional mav-agent-config.yaml file lets you enrich this Agent Card with:

Custom agent card name and description
Provider branding (organization, URL)
Skill-level tags for discovery
Usage examples for each skill
Custom input/output MIME types

Quick Start

Create mav-agent-config.yaml in your agent directory (alongside langgraph.json):

# mav-agent-config.yaml uses a namespaced structure
a2a:
  agent_card:
    name: "My Research Assistant"
    description: "An AI-powered research assistant"

  skills:
    research_agent:  # Must match graph name in langgraph.json
      tags: ["research", "academic", "citations"]
      examples:
        - "Find papers about quantum computing"
        - "Summarize recent AI safety research"

That's it. The next time AgentVisor starts, it will merge this configuration into the generated Agent Card.

Namespaced Configuration

The mav-agent-config.yaml file uses a namespaced structure where each top-level key represents a configuration domain. A2A-specific configuration lives under the a2a: key. This design allows future extensions without breaking compatibility — unknown top-level keys produce warnings but don't cause errors.

Configuration Reference

Agent Card Overrides

Top-level overrides applied to the entire Agent Card:

Field	Type	Description	Limit
`name`	string	Agent card display name	128 chars
`description`	string	Agent description	1024 chars
`provider.organization`	string	Your organization name	128 chars
`provider.url`	string	Your organization URL	Valid URI
`default_input_modes`	string[]	Default MIME types accepted by all skills	-
`default_output_modes`	string[]	Default MIME types produced by all skills	-

Skill Configuration

Per-skill overrides keyed by graph name (must match langgraph.json):

Field	Type	Description	Limit
`name`	string	Override skill display name	128 chars
`description`	string	Override skill description	1024 chars
`tags`	string[]	Categorization tags for discovery	20 tags, 64 chars each
`examples`	string[]	Example prompts demonstrating usage	10 examples, 500 chars each
`input_modes`	string[]	MIME types accepted (overrides defaults)	-
`output_modes`	string[]	MIME types produced (overrides defaults)	-

Complete Example

Here's a full example for a multi-agent research assistant:

# mav-agent-config.yaml
a2a:
  agent_card:
    name: "Acme Research Suite"
    description: "A comprehensive research toolkit powered by AI"
    provider:
      organization: "Acme Research Inc."
      url: "https://research.acme.com"
    default_input_modes:
      - "text/plain"
    default_output_modes:
      - "text/plain"
      - "text/markdown"

  skills:
    # Graph name from langgraph.json: "research": "./research.py:graph"
    research:
      name: "Academic Research"
      description: "Search and analyze academic papers across multiple databases"
      tags:
        - "research"
        - "academic"
        - "papers"
        - "citations"
      examples:
        - "Find papers about transformer architectures published after 2020"
        - "What are the key findings in recent quantum computing research?"
        - "Compare methodologies used in climate modeling papers"

    # Graph name from langgraph.json: "summarize": "./summarize.py:graph"  
    summarize:
      name: "Document Summarizer"
      description: "Generate concise summaries of long documents"
      tags:
        - "summarization"
        - "documents"
        - "analysis"
      examples:
        - "Summarize this research paper in 3 bullet points"
        - "What are the main arguments in this article?"
      input_modes:
        - "text/plain"
        - "text/markdown"
        - "application/pdf"
      output_modes:
        - "text/markdown"

    # Graph name from langgraph.json: "cite": "./cite.py:graph"
    cite:
      tags:
        - "citations"
        - "bibliography"
      examples:
        - "Generate a bibliography for these sources in APA format"

Supported MIME Types

MIME types follow the standard IANA format (type/subtype):

MIME Type	Description
`text/plain`	Plain text
`text/markdown`	Markdown formatted text
`application/json`	JSON data
`application/pdf`	PDF documents
`image/png`	PNG images
`image/jpeg`	JPEG images
`image/*`	Any image type

For backward compatibility, the shorthand values text and json are also accepted (equivalent to text/plain and application/json).

Editor Integration

For VS Code and other editors that support JSON Schema, add this to the top of your mav-agent-config.yaml:

# yaml-language-server: $schema=https://agentvisor.dev/schemas/mav-agent-config.schema.json

a2a:
  agent_card:
    name: "My Agent"
    # ... rest of config

This enables autocomplete and validation in supported editors.

Validation

The configuration is validated when the guest runtime starts. Validation errors (field length/format violations) are reported in the logs and prevent the agent from registering. A skill key that doesn't match any graph name is not a validation error — it only logs a warning (mav-agent-config.yaml references unknown agent) and the agent still registers without that skill's metadata applied.

Common Errors

Error	Cause	Fix
`name exceeds maximum length of 128 characters`	Name too long	Shorten the name
`tag[N] exceeds maximum length of 64 characters`	Tag too long	Use shorter tags
`skill may have at most 20 tags`	Too many tags	Remove less important tags
`invalid media type format`	Malformed MIME type	Use format `type/subtype`
`unknown top-level type`	Invalid MIME type category	Use valid types: text, application, image, etc.

Validation Constraints

Field	Constraint
Names	Max 128 characters
Descriptions	Max 1024 characters
Tags	Max 20 per skill, 64 characters each
Examples	Max 10 per skill, 500 characters each
MIME types	Must be valid IANA format or `text`/`json` shorthand

How It Works

Startup: The guest runtime looks for mav-agent-config.yaml in the agent directory
Validation: Configuration is parsed and validated against constraints
Merge: Valid A2A metadata is attached to each graph definition
Registration: The host runtime receives the enriched graph definitions via gRPC
Agent Card: When clients fetch /.well-known/agent-card.json, skills include the A2A metadata

The mav-agent-config.yaml file is entirely optional. If not present, the Agent Card uses default values derived from langgraph.json.

File Discovery

AgentVisor looks for the agent config file in this order:

mav-agent-config.yaml in the agent directory
mav-agent-config.yml in the agent directory (alternative extension)

If neither file exists, no error is raised — the feature is simply not used.

Overview​

Quick Start​

Configuration Reference​

Agent Card Overrides​

Skill Configuration​

Complete Example​

Supported MIME Types​

Editor Integration​

Validation​

Common Errors​

Validation Constraints​

How It Works​

File Discovery​

See Also​