Skip to main content

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.

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 
Authorization: Bearer <WHYOPS_API_KEY>
Content-Type: application/json

​
Request body

{
  "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"
      }
    ]
  }
}
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:

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