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
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 |
Key Capabilities
A2A Agent Registration (Available)
A2A Agent Registration (Available)
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) |
Health Monitoring
Health Monitoring
Periodic multi-level health probes ensure agents are reachable and functioning:
All probes include SSRF protection to prevent internal network scanning.
| 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? |
Lifecycle Management
Lifecycle Management
Track agents through their full lifecycle with administrative status and lifecycle stages:Administrative Status: PENDING, ACTIVE, SUSPENDED, DEREGISTEREDLifecycle Stage: EXPERIMENTAL, STABLE, DEPRECATED, RETIRED
Version History
Version History
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 Governance
Enterprise Governance
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
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)
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
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
WhenTALK2DATA_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 |
X-Project-ID header. If TALK2DATA_BASE_URL is not set, the tools return a talk2data_not_configured error. See 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 FQNlist_metadata_mcp— List metadata assets with filteringsearch_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
Data Connections
Configure data source connections used by agents for data access.
Webhooks
Set up webhook notifications for agent lifecycle events.
Data Insights Agents
See how Data Insights uses A2A agents for conversational analytics.
Security Model
Understand authentication, authorization, and multi-tenant isolation.