AgentCard

The AgentCard is a JSON file describing an Agent’s capabilities, acting as the Agent’s “business card.” It enables clients (or other Agents) to discover and understand what functionalities an Agent offers.

It is officially recommended to host the AgentCard at a specific path under the Agent service’s base URL: https://<base_url>/.well-known/agent.json. This allows clients to retrieve the AgentCard via a simple HTTP GET request, thereby learning the Agent’s details.

This design naturally suggests the need for Agent registries, whether public or private, to facilitate easier Agent lookup. Simultaneously, it opens possibilities for decentralized Agent discovery mechanisms, such as broadcasting AgentCards over P2P networks or even storing them on IPFS or blockchain to build self-organizing Agent networks.

AgentCard Structure

An AgentCard contains the following key information:

• Basic Information: Agent’s name (name), description (description), service URL (url), provider information (provider), version (version), documentation link (documentationUrl).
• Capabilities: Optional capabilities supported by the Agent, such as support for streaming (streaming), push notifications (pushNotifications), state transition history (stateTransitionHistory).
• Authentication Requirements: Authentication schemes required by the Agent (e.g., Basic, Bearer) and credential information.
• Default Interaction Modes: Default input (defaultInputModes) and output (defaultOutputModes) MIME types supported by the Agent across all skills.
• Skills: Specific capability units that the Agent can perform. Each skill includes:
  • Unique identifier (id)
  • Name (name)
  • Description (description)
  • Tags (tags)
  • Examples (examples)
  • Skill-specific input/output modes (inputModes/outputModes) (if different from default).

Below is an illustrative definition of the AgentCard interface (TypeScript style):

interface AgentCard {
  // Human-readable name for the Agent (e.g., "Recipe Agent")
  name: string;
  // Human-readable description of the Agent's function
  description: string;
  // URL address where the Agent is hosted
  url: string;
  // Service provider information for the Agent
  provider?: {
    organization: string;
    url: string;
  };
  // Version of the Agent (format defined by provider, e.g., "1.0.0")
  version: string;
  // URL for the Agent's documentation
  documentationUrl?: string;
  // Optional capabilities supported by the Agent
  capabilities: {
    streaming?: boolean; // If the Agent supports SSE
    pushNotifications?: boolean; // If the Agent can push update notifications to the client
    stateTransitionHistory?: boolean; // If the Agent exposes task state change history
  };
  // Authentication requirements for the Agent (intended to match OpenAPI auth structure)
  authentication: {
    schemes: string[]; // e.g., Basic, Bearer
    credentials?: string; // Credentials for the client to use for private Cards
  };
  // Default interaction modes supported by the Agent across all skills
  defaultInputModes: string[]; // Supported input MIME types
  defaultOutputModes: string[]; // Supported output MIME types
  // Collection of capability units the Agent can perform
  skills: {
    id: string; // Unique identifier for the skill
    name: string; // Human-readable name for the skill
    description: string; // Skill description
    tags: string[]; // Tags describing the skill's capability category (e.g., "cooking", "customer support")
    examples?: string[]; // Example scenarios or prompts the skill can execute (e.g., "I need a recipe for bread")
    inputModes?: string[]; // Input MIME types supported by the skill (if different from default)
    outputModes?: string[]; // Output MIME types supported by the skill (if different from default)
  }[];
}

Refer to the official or relevant implementations for the complete Schema definition.