aam

Agent-to-Agent Manager (AAM)

A tool for creating and managing agents conforming to the Agent-to-Agent (A2A) protocol

Getting Started

⚡️ Features

  ✓  Create A2A-compliant agent cards in .well-known/agent.json
  ✓  Manage agent skills according to A2A protocol
  ✓  Search for agents in registries
  ✓  Search for skills in registries
  ✓  Import skills from registries to agent cards
  ✓  Register agents in curated registries
  ✓  Interactive wizard interface with colorful UI

📖 About A2A Protocol

The Agent-to-Agent (A2A) protocol is designed to enable AI agents to discover and collaborate with each other. The protocol standardizes how agents describe themselves and their capabilities through "Agent Cards" which are hosted at a well-known location (typically .well-known/agent.json).

Learn more about the A2A protocol at Google's A2A Protocol Documentation.

✍️ Getting Started

Requirements

• Node.js >= 14.16.0 (required for ES Modules support)

Install with npm

npm install -g aam

Using as an ES Module

AAM is implemented as an ES Module, which means you can import its functions directly in your JavaScript files:

import { createAgentCard, initialize, addSkill } from 'aam/lib/index.js'

// Initialize a new project
const init = initialize()

// Create an agent card
const agent = createAgentCard({
  name: 'My Agent',
  description: 'A custom A2A agent',
  url: 'https://example.com/a2a'
})

// Add a skill
const skill = {
  id: 'custom-skill',
  name: 'Custom Skill',
  description: 'A custom skill',
  inputModes: ['text'],
  outputModes: ['text']
}
addSkill(skill)

Interactive Wizard

AAM includes an interactive wizard-style interface to guide you through the process of creating and managing agents with a colorful and user-friendly CLI:

aam wizard

The wizard provides a step-by-step interface for:

• Creating and managing agent cards
• Adding and importing skills
• Searching the registry for agents and skills
• Registering your agent to the registry

This is the recommended approach for new users or when you prefer an interactive experience over command-line arguments.

Initialize the project

Create the necessary templates and directories:

aam init

Create an agent card

Create an A2A-compliant agent card in .well-known/agent.json:

aam create-agent --name "My Agent" --description "A custom A2A agent" --url "https://example.com/a2a"

Optional parameters:

• --provider-name: Name of the agent provider
• --provider-url: URL of the agent provider
• --version: Version of the agent

Add a skill to an agent

Add a custom skill to your agent card:

aam add-skill --id "custom-skill" --name "Custom Skill" --description "A custom skill" --input-modes "text" --output-modes "text"

Optional parameters:

• --example-input: Example input for the skill
• --example-output: Example output for the skill
• --card: Path to the agent card (default: .well-known/agent.json)

Import a skill from registry

Import a skill from the registry to your agent card:

aam import-skill text-generation

Optional parameters:

• --card: Path to the agent card (default: .well-known/agent.json)
• --registry: Path to the skills registry (default: built-in registry)

Search for agents in registry

Search for agents in the registry:

aam search-agents chatbot

Optional parameters:

• --registry: Path to the agents registry (default: built-in registry)

Search for skills in registry

Search for skills in the registry:

aam search-skills image

Optional parameters:

• --registry: Path to the skills registry (default: built-in registry)

Register an agent in registry

Register your agent in the registry:

aam register-agent

Optional parameters:

• --card: Path to the agent card (default: .well-known/agent.json)
• --registry: Path to the agents registry (default: built-in registry)

Display help information

Display help information about all commands:

aam help

The supported commands are:

• init: Initialize the project with necessary templates and directories
• wizard: Start the interactive wizard with colorful UI
• create-agent: Create an agent card in .well-known/agent.json
• add-skill: Add a skill to an agent card
• import-skill: Import a skill from registry to agent card
• search-agents: Search for agents in the registry
• search-skills: Search for skills in the registry
• register-agent: Register an agent in the registry

🔍 Agent Discovery

The A2A protocol provides several strategies for discovering agents:

• Well-Known URI: Agents host their card at .well-known/agent.json following RFC 8615.
• Curated Registries: Agents can be registered in and discovered via centralized registries.
• Direct Configuration: Agents can be configured with direct knowledge of each other.

AAM supports all these discovery methods and makes it easy to generate compliant agent cards.

📝 Example Agent Card

Here's an example of an agent card in A2A protocol format:

{
  "name": "Text Generation Agent",
  "description": "An agent that can generate text content using AI",
  "url": "https://example.com/agents/text-generation",
  "version": "1.0.0",
  "provider": {
    "name": "Example AI",
    "url": "https://example.ai"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "multiTurn": true
  },
  "authentication": {
    "schemes": [
      {
        "type": "Bearer",
        "description": "JWT token authentication"
      }
    ]
  },
  "skills": [
    {
      "id": "text-generation",
      "name": "Text Generation",
      "description": "Generate text content based on prompts",
      "inputModes": ["text"],
      "outputModes": ["text"],
      "examples": [
        {
          "input": { "text": "Write a short poem about the moon" },
          "output": {
            "text": "Silver orb in night's embrace,\nCasting light on Earth's dark face.\nAncient witness, timeless grace,\nGuiding dreamers through space."
          }
        }
      ]
    }
  ]
}

📝 Example Skill Format

Here's an example of a skill in A2A protocol format:

{
  "id": "language-translation",
  "name": "Language Translation",
  "description": "Translate text between languages",
  "inputModes": ["text"],
  "outputModes": ["text"],
  "parameters": {
    "targetLanguage": {
      "type": "string",
      "required": true,
      "description": "The language code to translate to"
    }
  },
  "examples": [
    {
      "input": {
        "text": "Hello, world!",
        "parameters": {
          "targetLanguage": "fr"
        }
      },
      "output": { "text": "Bonjour, monde!" }
    }
  ]
}

⚖️ License

This project is under the MIT License. See the LICENSE file for the full license text.