> ## 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.
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.
## 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
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) |
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.
Track agents through their full lifecycle with administrative status and lifecycle stages:
**Administrative Status:** PENDING, ACTIVE, SUSPENDED, DEREGISTERED
**Lifecycle Stage:** EXPERIMENTAL, STABLE, DEPRECATED, RETIRED
Immutable version snapshots are created on every update to an agent's registration. The registry supports version diffing and rollback to any previous version.
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
## 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
Configure data source connections used by agents for data access.
Set up webhook notifications for agent lifecycle events.
See how Data Insights uses A2A agents for conversational analytics.
Understand authentication, authorization, and multi-tenant isolation.