> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Registry

> Unified registry for discovering, managing, and monitoring A2A agents, MCP servers, and agentskills.io skills at enterprise scale.

# Agent Registry

The Agent Registry provides a discovery layer for AI agents and tools. The core A2A Agent Registry is available now with full CRUD, fine-grained authorization, and event streaming.

The registry fills the explicit gap in the A2A specification, which acknowledges the need for curated registries but does not prescribe a standard API for them.

<Info>
  The A2A specification states: *"The current A2A specification does not prescribe a standard API for curated registries"* and *"The A2A community explores standardizing registry interactions or advanced discovery protocols."* The Agent Registry is designed to fill this gap with enterprise-grade capabilities.
</Info>

## The Discovery Problem

The A2A protocol v1.0 defines three agent discovery strategies, two of which are limited:

| Strategy | Limitation |
| - | - |
| **Well-Known URI** (`/.well-known/agent-card.json`) | Requires knowing the agent's domain upfront |
| **Curated Registries** | Acknowledged as needed but explicitly unspecified |
| **Direct Configuration** | Hardcoded and inflexible |

Meanwhile, the MCP ecosystem has its own public registry, and agentskills.io provides a portable skill format. These three ecosystems are complementary but fragmented -- no unified discovery layer exists.

## Key Capabilities

<AccordionGroup>
  <Accordion title="A2A Agent Registration (Available)" icon="id-card">
    RESTful CRUD for Agent Cards with full schema validation, optimistic concurrency control, and fine-grained authorization. Agents can register, update, and manage their A2A-compliant Agent Cards through the registry API. Auto-detects A2A protocol version (0.3 vs 1.0) from card structure. SHA-256 card hash for duplicate detection.

    **API surface:**

    | Method | Endpoint | Description |
    | - | - | - |
    | POST | `/agents` | Register agent (201 + Location + ETag) |
    | GET | `/agents` | List with pagination, status/tag/version filters |
    | GET | `/agents/{resource_uri}` | Get by URI (ETag) |
    | PUT | `/agents/{resource_uri}` | Update card with If-Match version guard |
    | DELETE | `/agents/{resource_uri}` | Permanent delete, cleans up authorization tuples |
    | POST | `/agents/validate` | Dry-run card validation (no DB write) |
  </Accordion>

  <Accordion title="Health Monitoring" icon="heart-pulse">
    Periodic multi-level health probes ensure agents are reachable and functioning:

    | Level | Check | Purpose |
    | - | - | - |
    | **L1** | Endpoint reachability | Is the agent's URL responding? |
    | **L2** | Card freshness | Has the Agent Card been updated recently? |
    | **L3** | Protocol probe | Does the agent respond to A2A/MCP protocol requests? |

    All probes include SSRF protection to prevent internal network scanning.
  </Accordion>

  <Accordion title="Lifecycle Management" icon="arrows-rotate">
    Track agents through their full lifecycle with administrative status and lifecycle stages:

    **Administrative Status:** PENDING, ACTIVE, SUSPENDED, DEREGISTERED

    **Lifecycle Stage:** EXPERIMENTAL, STABLE, DEPRECATED, RETIRED
  </Accordion>

  <Accordion title="Version History" icon="clock-rotate-left">
    Immutable version snapshots are created on every update to an agent's registration. The registry supports version diffing and rollback to any previous version.
  </Accordion>

  <Accordion title="Enterprise Governance" icon="building-shield">
    Enterprise-grade controls including:

    * Approval workflows for new agent registrations
    * Registration policies and change windows
    * Audit logging of all operations
    * Compliance reporting
    * Tenant-scoped administration with optional cross-tenant federation
  </Accordion>
</AccordionGroup>

## Architecture

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
stateDiagram-v2
    [*] --> PENDING : POST /agents/register
    PENDING --> ACTIVE : L1+L2+L3 health probes pass
    ACTIVE --> SUSPENDED : admin suspend or health failure
    SUSPENDED --> ACTIVE : admin reactivate
    ACTIVE --> DEPRECATED : lifecycle transition
    DEPRECATED --> RETIRED : end-of-life
    SUSPENDED --> DEREGISTERED : admin delete
    ACTIVE --> DEREGISTERED : admin delete
    RETIRED --> DEREGISTERED : admin delete
    DEREGISTERED --> [*]
```

The Agent Registry follows a stateless API architecture backed by proven platform infrastructure, OIDC authentication, fine-grained authorization, event streaming, and relational storage.

## Artifact Preview

Agents produce artifacts (query results, generated reports, intermediate data) that the platform can preview without forcing a full download. The Assets service exposes a preview endpoint that returns a structured snapshot of an artifact.

**Defaults** (effective with em-runtime 5.3+):

* Default row limit: **500 rows** (raised from 10)
* Maximum byte budget: **512 KB** per response (raised from 64 KB)
* Maximum row limit: **10,000 rows** (cap regardless of caller request)

**Response metadata** (`PreviewMetadata`):

* `size_bytes`: total file size for tabular, text, and raw artifacts (always present)
* `truncated`: boolean flag set when either the row limit or the byte budget was reached

The service applies a byte-level truncation backstop after row-level limits, so a response that cuts cleanly at a record boundary still respects `max_bytes`. Callers should always check `truncated` before assuming a preview reflects the full artifact.

## MCP Tool Integrations

The em-runtime MCP server exposes tool sets that agents can invoke via the Model Context Protocol. These tools proxy authenticated calls to platform services using the caller's JWT and project context.

### Talk2Data Tools

When `TALK2DATA_BASE_URL` is configured, the following tools are available:

| Tool | Description |
| - | - |
| `generate_sql_mcp` | Generate SQL from a natural-language question against a specified data source and schema |
| `execute_query_mcp` | Execute a SQL query against a data connection and return results |
| `resolve_term_mcp` | Resolve a business term to its canonical definition using the data catalog |
| `generate_plotly_chart_mcp` | Generate a Plotly chart specification from query results |

These tools forward requests to the Talk2Data Service using the caller's bearer token and `X-Project-ID` header. If `TALK2DATA_BASE_URL` is not set, the tools return a `talk2data_not_configured` error. See [Data Insights Overview](/data-insights/overview) for Talk2Data deployment.

### Catalog Tools

The MCP server also exposes metadata and search tools against the Utils service (data catalog):

* **`get_schema_mcp`** — Get schema metadata for a data connection entity by FQN
* **`list_metadata_mcp`** — List metadata assets with filtering
* **`search_metadata_mcp`** — Full-text search across the data catalog

## Webhook Events

The registry emits events after successful registration operations.

| Event Category | Examples |
| - | - |
| **Registration** | Agent registered, updated, deregistered |
| **Health** | Health status changed, probe failed |
| **Lifecycle** | Stage transition (e.g., EXPERIMENTAL to STABLE) |
| **Search** | New agent matches a saved search filter |

## Well-Known URI Crawling

The registry can automatically discover agents from configured domains by crawling their `/.well-known/agent-card.json` endpoints:

* Scheduled crawls with configurable intervals
* Caching to minimize network traffic
* **Drift detection** to identify when a remote Agent Card changes
* SSRF protection for all outbound requests

## Multi-Tenancy

The registry supports full multi-tenant isolation:

* **Namespace isolation** -- each tenant's agents are invisible to other tenants
* **Tenant-scoped administration** -- per-tenant admin roles and policies
* **Cross-tenant federation** -- optional sharing of selected agents across tenants
* **Cost attribution** -- per-tenant usage metering, quota enforcement, and chargeback

## Target Personas

| Persona | Use Case |
| - | - |
| **Agent Developer** | Register, update, and manage A2A Agent Cards. Validate cards before publishing. Track health and manage versions. |
| **MCP Server Developer** | Register MCP server metadata (tools, resources, prompts). Validate tool schemas. Publish to both this registry and the MCP public registry. |
| **Consumer** | Search by skill tags, keywords, provider, capabilities, and protocol. Filter by health and verification status. |
| **Platform Operator** | Deploy and scale the registry. Monitor health, latency, and throughput. Configure health check intervals. |
| **Enterprise Admin** | Control registration policies. Configure approval workflows. Audit operations. Enforce security policies. |

## Success Metrics

| Metric | Target |
| - | - |
| API availability | 99.9% monthly |
| Search p99 latency | \< 500ms |
| Registration p99 latency | \< 1000ms |
| Search index lag | \< 30 seconds |
| Webhook first delivery | \< 60 seconds |
| Registered entities capacity | 100K+ agents and servers |
| Search throughput | 1K+ queries/second |

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Connections" icon="database" href="/platform/data-connections">
    Configure data source connections used by agents for data access.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/platform/webhooks">
    Set up webhook notifications for agent lifecycle events.
  </Card>

  <Card title="Data Insights Agents" icon="chart-bar" href="/data-insights/overview">
    See how Data Insights uses A2A agents for conversational analytics.
  </Card>

  <Card title="Security Model" icon="shield" href="/security/overview">
    Understand authentication, authorization, and multi-tenant isolation.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.