> ## Documentation Index
> Fetch the complete documentation index at: https://whyops.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Registration API

> Register agents, create versioned configurations, and understand how WhyOps binds traces to agent versions when you are using the raw API directly.

Before WhyOps can give you high-quality agent analytics, it needs to know what your agent is.

That means registering:

* the stable `agentName` you send on requests
* the current system prompt
* the tools the agent can call
* optional descriptive metadata

This registration creates an **Agent** plus a versioned **Entity** record behind the scenes. Every trace is later bound to the latest matching agent version for that `agentName`.

<CardGroup cols={2}>
  <Card title="TypeScript SDK Setup" icon="code" href="/integrations/typescript-sdk">
    `@whyops/sdk` wraps this flow and auto-initializes on first trace event unless you call `initAgent()` explicitly during boot.
  </Card>

  <Card title="Python SDK Setup" icon="terminal" href="/integrations/python-sdk">
    `whyops` exposes `init_agent_sync()` and `init_agent()` so you can register on startup in sync or async services.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Agent Init Reference" icon="book" href="/integrations/agent-init-reference">
    Request fields, response shape, direct analyse endpoint, auto-init fallback, and follow-up entity APIs.
  </Card>

  <Card title="SDK Packages" icon="box-open" href="/integrations/sdk-packages">
    Compare the published integration packages before choosing your registration and tracing flow.
  </Card>
</CardGroup>

## Why this exists

WhyOps uses agent registration for four things:

1. **Versioning**: when your system prompt or tool contracts change, WhyOps creates a new agent version.
2. **Trace binding**: traces are attached to the latest version for the `agentName` in the current user/project/environment scope.
3. **Sampling**: default sampling rate is stored on agent versions and reused across traces.
4. **UI context**: the dashboard can show prompt, tools, version history, and config diffs.

## Recommended flow

<Steps>
  <Step title="Register the agent on deploy or startup">
    Call the init endpoint whenever you deploy a new prompt/tool configuration.
  </Step>

  <Step title="Send LLM traffic through the proxy">
    Include the same `X-Agent-Name` header on all LLM requests.
  </Step>

  <Step title="Optionally emit manual events">
    Use the same `agentName` and `traceId` for tool/runtime events you send manually.
  </Step>
</Steps>

## Proxy endpoint

If you are already using `whyops-proxy`, the easiest registration path is:

### `POST /v1/agents/init`

This endpoint exists on the proxy and tunnels the request to `whyops-analyse`.

**Auth**

```http theme={null}
Authorization: Bearer <WHYOPS_API_KEY>
Content-Type: application/json
```

### Request body

```json theme={null}
{
  "agentName": "customer-support-agent",
  "metadata": {
    "systemPrompt": "You are WhyOps Support. Be precise, polite, and use tools when needed.",
    "description": "Handles support, billing, and order status questions",
    "tools": [
      {
        "name": "search_orders",
        "inputSchema": "{\"type\":\"object\",\"properties\":{\"orderId\":{\"type\":\"string\"}},\"required\":[\"orderId\"]}",
        "outputSchema": "{\"type\":\"object\",\"properties\":{\"status\":{\"type\":\"string\"}}}",
        "description": "Find the latest status for a customer order"
      }
    ]
  }
}
```

<Callout type="warning" title="Schema format">
  `inputSchema` and `outputSchema` are currently expected as strings by the backend, so send serialized JSON schema strings rather than nested JSON objects.
</Callout>

## What happens internally

When you call init:

1. WhyOps looks up an existing `Agent` by `userId + projectId + environmentId + agentName`.
2. It computes a SHA-256-based hash from the `metadata` payload.
3. If the latest version already has the same hash, WhyOps returns the existing version with `status: "existing"`.
4. If the hash changed, WhyOps creates a new `Entity` version and carries forward the previous sampling rate.

## When to call init

Use one of these patterns:

<Tabs>
  <Tab title="On deploy (Recommended)">
    Call init once per deploy whenever your prompt or tool definitions change.
  </Tab>

  <Tab title="On service startup">
    Good for long-running worker or API services that boot with a known prompt configuration.
  </Tab>

  <Tab title="On agent build/publish">
    Best if you have an internal prompt registry or agent release pipeline.
  </Tab>
</Tabs>

## Full API contract

For field-level requirements, response payloads, the direct analyse endpoint, auto-init fallback behavior, and the entity follow-up APIs, see [Agent Init Reference](/integrations/agent-init-reference).