Skip to main content

​
1. Install

Install the SDK with the extra for the provider your agent uses:
The PyPI distribution is visceral-ai; the import name is visceral. Python 3.10+ is required.

​
2. Authenticate

Create a workspace API key from the dashboard, and put it in the environment:
That key is the only secret the SDK needs. By default it reports to https://api.visceralai.dev.

​
3. Wrap your client

Wrap the LLM client your agent already uses and give the agent a stable name. wrap() returns the same client object, instrumented:
That’s it — your agent behaves identically, and its LLM traffic now shows up in Visceral. Prompt and response text never leave your process: content is stripped in the SDK before anything is exported. If the backend is unreachable, the wrapped client falls straight through to the underlying provider (fail open).

​
Optional: turn on optimization

Observation is the default. When you’re ready, opt in to the optimizations Visceral has proven safe for your traffic — cache-layout rewrites and tool-call reuse — with one flag:
See Optimization for exactly what this does — and what it will never do.

​
Next steps

Instrumenting your agent

The full wrap() surface plus instrument() for frameworks (LangChain, LlamaIndex, CrewAI) and the node() decorator.

Tool-call reuse

Annotate tools with @tool so proven-safe read-only calls are served, not re-run.

Optimization

What apply=True rewrites, how rules reach the SDK, and the guardrails.

Configuration

Every environment variable the SDK reads, and its default.