A2A Agent Cards

Publish and discover agent capabilities using Google's Agent-to-Agent (A2A) protocol. Agent Cards let agents advertise their skills and security posture so other agents can discover and delegate tasks.

What Is A2A?

The Agent-to-Agent protocol (A2A v0.2) defines a standard format for agents to describe themselves — what tools they use, what tasks they can handle, and what security policies they enforce. Navil implements the full spec: agent card generation, discovery via /.well-known/agent.json, and task dispatch with governance.

Discovery flow

Agent A → GET /.well-known/agent.json → Navil Proxy
    → Returns AgentCard with capabilities + security info
    → Agent A learns: auth method, skills, endpoint URL
    → Agent A → POST /a2a/tasks/send → Navil Proxy → Agent B

Agent Card Format

The agent card includes identity, capabilities, skills, authentication requirements, and Navil-specific governance extensions:

agent-card.json

{
  "name": "data-analyst",
  "description": "Queries databases and generates reports",
  "provider": {
    "organization": "Acme Corp",
    "url": "https://acme.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": true
  },
  "skills": [
    {
      "id": "mcp-tool-execution",
      "name": "MCP Tool Execution",
      "description": "Execute MCP server tools with governance",
      "tags": ["mcp", "tools", "governance"],
      "examples": ["Run a database query", "Read a file"]
    }
  ],
  "securitySchemes": {
    "navil_jwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT",
      "description": "Navil-issued JWT with agent identity"
    }
  },
  "security": [{ "navil_jwt": [] }],
  "interfaces": [
    {
      "protocol": "jsonrpc",
      "url": "https://example.com/a2a",
      "contentTypes": ["application/json"]
    }
  ],
  "extensions": [
    {
      "name": "navil-governance",
      "version": "1.0.0",
      "fields": {
        "governance_endpoint": "https://example.com/mcp",
        "supports_scoping": true,
        "supports_threat_detection": true
      }
    }
  ]
}

Publishing Your Agent Card

Navil auto-generates an agent card from your configuration and environment variables, then serves it at /.well-known/agent.json. Customize it with environment variables or explicit arguments:

Terminal

# Set agent identity via environment
export NAVIL_AGENT_NAME="my-analyst"
export NAVIL_AGENT_DESCRIPTION="Queries databases and generates reports"
export NAVIL_BASE_URL="https://my-agent.example.com"
export NAVIL_PROVIDER_ORG="Acme Corp"
export NAVIL_PROVIDER_URL="https://acme.com"

# Start the proxy — agent card is served automatically
navil proxy --target http://localhost:3000

# Verify your card
curl http://localhost:9090/.well-known/agent.json

Skills

Skills describe what tasks your agent can perform. Each skill has an ID, name, description, tags, and example prompts. By default, Navil advertises an MCP tool execution skill, but you can define custom skills for your agent:

Custom skills

{
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Run SQL queries and generate charts",
      "tags": ["data", "sql", "charts"],
      "examples": ["Analyze Q4 revenue trends"]
    },
    {
      "id": "code-review",
      "name": "Code Review",
      "description": "Review PRs for security issues",
      "tags": ["security", "code", "review"],
      "examples": ["Review PR #123 for SQL injection"]
    }
  ]
}

Discovering Other Agents

The dashboard's A2A page lets you discover agents on your network, inspect their capabilities, and dispatch tasks. Access it at http://localhost:8484/agent-card.

Task Dispatch

Once you discover another agent, you can delegate tasks to it through the A2A protocol. Tasks flow through Navil's governance layer with full auth and policy checks:

Task lifecycle

sendMessage → Task (pending)
    → Navil auth + policy check
    → Agent B processes task (working)
    → Response through Navil (telemetry)
    → Task (completed)

getTask    → Check task state at any time
cancelTask → Cancel a pending or working task

Navil handles credential delegation and scope narrowing automatically — the child agent only gets access to the tools it needs for the delegated task. The X-Navil-Scope header propagates through the delegation chain.

Governance Extension

Navil-protected agents include a navil-governance extension in their agent card. This advertises that the agent has policy enforcement, tool scoping, and threat detection enabled — letting other agents make trust decisions before delegating tasks.

AI Policy Builder

CLI Events & Shim