Skip to main content
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.

TypeScript SDK Setup

@whyops/sdk wraps this flow and auto-initializes on first trace event unless you call initAgent() explicitly during boot.

Python SDK Setup

whyops exposes init_agent_sync() and init_agent() so you can register on startup in sync or async services.

Agent Init Reference

Request fields, response shape, direct analyse endpoint, auto-init fallback, and follow-up entity APIs.

SDK Packages

Compare the published integration packages before choosing your registration and tracing flow.

​
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.
1

Register the agent on deploy or startup

Call the init endpoint whenever you deploy a new prompt/tool configuration.
2

Send LLM traffic through the proxy

Include the same X-Agent-Name header on all LLM requests.
3

Optionally emit manual events

Use the same agentName and traceId for tool/runtime events you send manually.

​
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

​
Request body

inputSchema and outputSchema are currently expected as strings by the backend, so send serialized JSON schema strings rather than nested JSON objects.

​
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:
Call init once per deploy whenever your prompt or tool definitions change.

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