Skip to main content

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.

​
Register Your First Agent

CRAFT is an agent platform built on the A2A protocol. Every capability — from natural-language data queries to semiconductor yield analysis — runs as a discrete, independently deployable agent. This guide explains what you can build on CRAFT, who it is for, and where to find the detailed authoring documentation.

​
What This Guide Covers

This guide walks you through the final step of agent deployment: registering your agent in the CRAFT Assets registry. Once registered, your agent becomes discoverable to orchestrators and other platform consumers via the A2A protocol. Registration involves three steps: authoring an A2A-compliant Agent Card, validating it with the platform’s dry-run endpoint, and posting it to the Assets API. You will also learn how to list, fetch, update, and delete registered agents. This tutorial is suitable for developers and operators who have already built and deployed an agent service that exposes an Agent Card at /.well-known/agent-card.json. If you have not built your agent yet, start with the framework-specific authoring guides below.

​
Who This Guide Is For

This guide is written for two audiences:
  • Developers deploying a new agent service to CRAFT for the first time, who need to register it so the orchestrator can discover and invoke it
  • Operators managing the agent registry — listing active agents, promoting lifecycle stages, or cleaning up retired registrations
If you are building a new agent from scratch, you need prerequisites beyond what this guide covers: a framework choice, tool authoring, streaming implementation, and evaluation setup.

​
Register Your Agent

Once your agent service is running and its Agent Card is accessible, use the Assets API to register it on CRAFT.
1

Authenticate with the platform

Obtain a JWT token from the platform identity provider to authenticate with the platform APIs.
TOKEN=$(curl -s -X POST \
  "https://<auth-host>/realms/<org-id>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>" \
  | jq -r '.access_token')
For local development, use make get-token in the em-runtime repository to obtain a token for the org admin user.
2

Validate the Agent Card (optional)

Use the validation endpoint to check your Agent Card before registering it. This is a dry-run with no database write.
curl -X POST "https://<platform-host>:8002/assets/agents:validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-ID: <your-project-id>" \
  -H "Content-Type: application/json" \
  -d @agent-card.json
A valid card returns {"valid": true, "errors": [], "warnings": []}.
3

Register the agent

curl -i -X POST "https://<platform-host>:8002/assets/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-ID: <your-project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_card": '"$(curl -s https://my-agent.example.com/.well-known/agent-card.json)"',
    "tags": ["demo"],
    "visibility": "TENANT_ONLY"
  }'
A successful registration returns 201 Created with a Location header and ETag. The platform generates a resource_uri from the agent name, organization, and project: agent:{org_id}:{project_id}:{name}.
4

Verify the registration

curl "https://<platform-host>:8002/assets/agents?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-ID: <your-project-id>"
Your agent should appear in the listing with status: ACTIVE and lifecycle_stage: EXPERIMENTAL.

​
Lifecycle Stages

New registrations default to EXPERIMENTAL. The lifecycle stage tracks agent maturity.
StageDescription
EXPERIMENTALInitial registration, under development
STABLEProduction-ready, fully tested
DEPRECATEDScheduled for removal, still functional
RETIREDNo longer available
Stage transitions are managed by the platform. UpdateAgentRequest accepts agent_card, tags, and visibility — not lifecycle_stage directly.

​
Troubleshooting

Verify your token has can_create_resources for the target project. Check that the X-Project-ID header matches a project you have access to.
An agent with the same name already exists in the project. Choose a unique name or use PUT to update the existing registration.
The Agent Card failed validation. Common causes: missing both url and supportedInterfaces, missing required name/version fields, or field length limits exceeded (255 chars for name, 2000 for description). Use :validate to surface specific errors.
The ETag you sent no longer matches — another update happened in between. Fetch the agent again with GET to retrieve the latest ETag, then retry.

​
Next Steps

Agent Registry

Learn about the full agent registry supporting A2A v0.3 and v1.0 protocols.

Data Source Setup

Connect a database so your agents can query real data.

RBAC Configuration

Configure fine-grained permissions for your agents and projects.

API Reference

Explore the full API documentation for the Assets service.