> ## 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

> Step-by-step tutorial to register, configure, and test your first A2A agent on CRAFT.

# 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.

<Steps>
  <Step title="Authenticate with the platform">
    Obtain a JWT token from the platform identity provider to authenticate with the platform APIs.

    ```bash theme={null}
    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')
    ```

    <Tip>
      For local development, use `make get-token` in the em-runtime repository to obtain a token for the org admin user.
    </Tip>
  </Step>

  <Step title="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.

    ```bash theme={null}
    curl -X POST "https://<platform-host>/api/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": []}`.
  </Step>

  <Step title="Register the agent">
    ```bash theme={null}
    curl -i -X POST "https://<platform-host>/api/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}`.
  </Step>

  <Step title="Verify the registration">
    ```bash theme={null}
    curl "https://<platform-host>/api/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`.
  </Step>
</Steps>

## Lifecycle Stages

New registrations default to `EXPERIMENTAL`. The lifecycle stage tracks agent maturity.

| Stage          | Description                             |
| -------------- | --------------------------------------- |
| `EXPERIMENTAL` | Initial registration, under development |
| `STABLE`       | Production-ready, fully tested          |
| `DEPRECATED`   | Scheduled for removal, still functional |
| `RETIRED`      | No longer available                     |

<Note>
  Stage transitions are managed by the platform. `UpdateAgentRequest` accepts `agent_card`, `tags`, and `visibility` — not `lifecycle_stage` directly.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="403 Forbidden when registering">
    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.
  </Accordion>

  <Accordion title="409 Conflict on registration">
    An agent with the same `name` already exists in the project. Choose a unique name or use `PUT` to update the existing registration.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    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.
  </Accordion>

  <Accordion title="412 Precondition Failed on update">
    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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Registry" icon="robot" href="/platform/agents">
    Learn about the full agent registry supporting A2A v0.3 and v1.0 protocols.
  </Card>

  <Card title="Data Source Setup" icon="database" href="/guides/data-source-setup">
    Connect a database so your agents can query real data.
  </Card>

  <Card title="RBAC Configuration" icon="user-shield" href="/guides/rbac-configuration">
    Configure fine-grained permissions for your agents and projects.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full API documentation for the Assets service.
  </Card>
</CardGroup>