Skip to main content
Use this page when you need the exact registration payload and follow-up API behavior behind POST /v1/agents/init.

Agent Init Overview

Start with the deployment flow, versioning rationale, and registration strategy.

TypeScript SDK Setup

@whyops/sdk wraps agent init and auto-registers on first trace event unless you call initAgent() explicitly.

Field requirements

Response shape

Direct analyse endpoint

If you are not using the proxy, call POST /api/entities/init on the analyse service. It accepts the same payload and returns the same response shape.

Auto-init fallback

If you skip explicit registration and start sending events first, whyops-analyse attempts best-effort auto-initialization during trace creation.
  • It extracts systemPrompt from event metadata when possible.
  • It infers tool definitions from event metadata when available.
  • Otherwise it creates a placeholder description.
This is useful for resilience, but it is not the preferred workflow because explicit init gives cleaner version history and better UI fidelity.

Minimal TypeScript example

  • GET /api/entities lists agents with usage and latest version.
  • GET /api/entities/:id returns one agent with versions and timelines.
  • GET /api/entities/:id/version-ids lists version IDs for an agent.
  • GET /api/entities/versions/:versionId fetches one exact version.
  • PATCH /api/entities/:id/sampling-rate updates version sampling rate.
  • DELETE /api/entities/:id hard-deletes an agent and linked runtime data.

Lifecycle reminder

The integration lifecycle is: register -> send traffic -> inspect traces -> tune settings -> evaluate.