Traylinx Agent Registry¶

The Traylinx Agent Registry is a central component of the Traylinx Agent Ecosystem. It serves as the "Yellow Pages" for autonomous agents, providing a secure, high-performance directory for agent registration, discovery, and lifecycle management.

Overview¶

The Registry enables agents to find and communicate with each other securely using the Stargate A2A (Agent-to-Agent) protocol. It handles:

Agent Registration: Identity management and endpoint publishing.
Dynamic Discovery: Finding agents based on capabilities, skills, and ranking.
Health Monitoring: Real-time heartbeat tracking to ensure discovery only returns healthy agents.
Agent Marketplace: A searchable catalog of agent manifests for orchestration and human-interactive browsing.

Tech Stack¶

Framework: FastAPI (Asynchronous Python)
Database: PostgreSQL for persistent storage.
Storage: SQLAlchemy with asyncpg for async DB operations.
Authentication: traylinx-auth-client for Stargate A2A secure communication.
Logging: structlog for structured, production-ready logging.

API Reference¶

The Registry exposes three primary router modules:

1. A2A Registry (`/a2a/registry`)¶

Standard protocol for agent identity and discovery.

POST /register: Register or update an agent descriptor.
POST /heartbeat: Update agent liveness status (204 No Content).
POST /deregister: Remove an agent from active rotation.
POST /discover: Search for agents matching specific requirements (ranked by performance).
POST /stats.report: Report performance metrics for ranking optimization.

2. A2A Catalog (`/a2a/catalog`)¶

Manage agent manifests and versioning.

POST /publish: Publish a new version of an agent manifest (YAML/JSON).
POST /unpublish: Remove an agent or specific version from the catalog.
POST /versions: List all available manifest versions for an agent.

3. Public Catalog (`/catalog`)¶

Read-only endpoints for browsing "Published" agents (no A2A auth required).

GET /search: Search published agents by query, domain, or tags.
GET /agents/{agent_key}: Retrieve detailed manifest for a specific agent.

Configuration¶

Key environment variables in .env:

Variable	Default	Description
`DATABASE_URL`	REQUIRED	PostgreSQL connection string
`ENV_NAMESPACE`	`dev`	Environment (dev/stg/prod)
`AGENT_TIMEOUT_SECONDS`	`180`	Time until agent is marked unhealthy
`TRAYLINX_CLIENT_ID`	REQUIRED	Auth client ID
`TRAYLINX_CLIENT_SECRET`	REQUIRED	Auth client secret
`ENABLE_A2A_ENDPOINTS`	`True`	Toggle A2A protocol support

Ranking Weights¶

The Registry ranks agents during discovery using: - Success Rate: 50% - Latency: 30% - Freshness: 20%

🔨 Development¶

Installation¶

poetry install

Running Locally¶

poetry run uvicorn app.main:app --reload

🚢 Deployment¶

The service is container-ready and typically deployed via Kubernetes.

Health Check: /health
Readiness Probe: /readiness (checks database connectivity)