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.

Use this page when you need the exact payload shape for a given event type or you are building your own runtime instrumentation without one of the SDK helpers.

Manual Events Overview

Start with the ingest endpoint, auth flow, queue behavior, and event schema summary.

Agent Registration

Register the agent first so manual events bind cleanly to the right versioned configuration.

​
Event payloads

user_messageUse for the assembled chat history or final prompt input your orchestrator produced.
[
  { "role": "system", "content": "You are helpful." },
  { "role": "user", "content": "Where is my order?" }
]

{
  "systemPrompt": "You are helpful.",
  "tools": [{ "name": "search_orders" }],
  "params": { "temperature": 0.2 }
}
llm_responseRequires metadata.model and metadata.provider.
{
  "content": "Your order has shipped.",
  "toolCalls": [],
  "finishReason": "stop"
}

{
  "content": null,
  "toolCalls": [
    {
      "function": {
        "name": "search_orders",
        "arguments": "{\"orderId\":\"123\"}"
      }
    }
  ],
  "finishReason": "tool_calls"
}

​
Runtime patterns

1

Proxy only

Send no manual events if the proxy already gives you the LLM visibility you need.
2

Full tool observability

Emit tool_call_request before execution and tool_call_response after completion, then optionally tool_result when the output is passed back to the model.
3

Internal retries

Use a different spanId per retry so the graph can show the retry pattern instead of collapsing multiple attempts together.

​
Idempotency and binding

  • If you provide idempotencyKey, WhyOps uses it to skip duplicates.
  • If you do not provide one, WhyOps may derive one from a content hash for most event types.
  • tool_call_request and tool_call_response intentionally skip content-hash dedup because repeated calls can be legitimate retries.
  • The first event for a new trace auto-creates the trace and binds it to the latest registered agent version for that agentName.
  • If the same traceId later resolves to a different agent version, WhyOps returns a conflict to protect trace consistency.

​
Best practices

  • Reuse the exact same spanId between tool_call_request and tool_call_response.
  • Include metadata.latencyMs whenever you measure provider or tool execution time.
  • Batch events to /api/events/ingest when you want lower network overhead.
  • Register agents explicitly with Agent Init and Registration before sending traffic.
  • Always send metadata.model and metadata.provider for llm_response and embedding_response.