# Self-registration with the agent-gateway

> Normative requirements: [SPEC.md §5](../SPEC.md#5-self-registration-with-the-gateway-must)

Every agent self-registers with the agent-gateway on startup. The gateway is the single Service in front of the registry catalogue and the proxy through which other agents (and Backstage) reach this agent's endpoints.

## Topology

```mermaid
sequenceDiagram
    participant A as Agent pod
    participant G as agent-gateway
    Note over A: lifespan startup
    A->>A: asyncio.sleep(2s)<br/>(let uvicorn bind)
    A->>G: POST /agents/register-url<br/>{"endpoint": AGENT_SELF_URL}
    G->>A: GET {AGENT_SELF_URL}/.well-known/agent.json
    A-->>G: 200 OK + manifest
    G-->>A: 201 Created (registration row)
```

## Configuration

Two environment variables drive the flow. Both **MUST** be set in the agent's ConfigMap.

| Var | Example | Purpose |
|---|---|---|
| `REGISTRY_URL` | `http://agent-gateway.agents.svc.cluster.local` | The gateway's base URL. |
| `AGENT_SELF_URL` | `http://policy-transformer.agents.svc.cluster.local` | The URL the gateway should call back on. |

Notes:

- The registry validates `AGENT_SELF_URL` against an SSRF allow-list. The host **MUST** end in `.svc.cluster.local` or `.kyndemo.live` and use `http` or `https`. Anything else is rejected with `400 Bad Request`.
- Cross-namespace `AGENT_SELF_URL` values are fine as long as the URL is resolvable in cluster DNS.
- The trailing path on `AGENT_SELF_URL` **MUST** be `/` (or empty); the gateway appends `/.well-known/agent.json` itself.

## The registration call

The canonical implementation lives in [`template/app/agent.py`](../template/app/agent.py). Key invariants:

- Initial sleep of 2 seconds **before** the first attempt — uvicorn needs time to bind the listen socket and the manifest route.
- 3 attempts total, 5 seconds between attempts, 10-second timeout per request.
- HTTP 200 *or* 201 are both treated as success.
- Logging:
  - `INFO` once on success.
  - `WARNING` per failed attempt with `HTTP <code>` + body excerpt.
  - `ERROR` once on final failure (after the third attempt).
- The task is created via `asyncio.create_task` inside the Starlette `lifespan`, so it does **not** block uvicorn from accepting traffic. A failed registration **MUST NOT** crash the agent.

## What the gateway does next

After the agent's `POST /agents/register-url` succeeds, the gateway performs:

1. `GET {endpoint}/.well-known/agent.json` (hardcoded path).
2. Parses the manifest into an `AgentRegistration` row keyed by the manifest's `name`, normalised to lower-hyphen-case.
3. Registers the agent in the catalogue.
4. Routes inbound traffic from `/proxy/agent-gateway/{agent_name}/{path}` to `{endpoint}/{path}`.

Therefore the manifest at `AGENT_SELF_URL` **MUST** be reachable and **MUST** match the schema in [docs/manifest.md](manifest.md).

## Failure modes & resolution

| Symptom | Cause | Fix |
|---|---|---|
| `HTTP 400 — Failed to fetch agent card from .../.well-known/agent.json: HTTP 404` | The agent has no manifest route. | Add `Route("/.well-known/agent.json", agent_manifest, methods=["GET"])`. |
| `HTTP 400 — ... HTTP 500` | The manifest route raises (e.g. `AgentSkill.model_dump` `AttributeError`). | Use the defensive `_skill_dict()` helper from the template. |
| `HTTP 400 — endpoint URL not allowed` | `AGENT_SELF_URL` host does not end in `.svc.cluster.local` or `.kyndemo.live`. | Fix the ConfigMap. |
| Three `WARNING`s + final `ERROR` but agent serves traffic fine | Gateway pod was restarting during agent startup. | Restart the agent pod once the gateway is `Ready`. Re-registration on next pod restart will recover. |

## Local development

When running outside the cluster, leave `REGISTRY_URL` unset (or set it to `""`) — the agent will log `REGISTRY_URL not set — skipping self-registration` and continue.