Requirements
- Python 3.10+
- An agent that calls OpenAI, Anthropic, or Google GenAI from Python
Install
The base package has no LLM SDK dependencies of its own. Install it with the
extra matching the provider(s) your agent uses so the right instrumentation is
pulled in:
Building on a framework instead? Add its extra so
instrument()
can capture it (these aren’t part of all-providers):
The PyPI distribution is named visceral-ai. The import name is visceral:
Anthropic users: stay on anthropic<1.0. anthropic 1.x removed an API
surface the instrumentation still imports, so under 1.x the SDK captures
zero LLM calls while your agent runs normally: everything looks
instrumented, and the dashboard shows an agent with no calls. Install with
the [anthropic] extra, which pins anthropic>=0.25,<1.0 for you (since
SDK 0.2.4); if you manage the provider pin yourself, keep the same cap. A
bare pip install visceral-ai on top of an incompatible provider SDK is the
trap this pin exists to avoid. Since 0.2.3 the SDK also warns loudly at
wrap() when an instrumentor fails to attach, instead of failing silently.
Authenticate
The SDK reads your workspace API key from the environment:
Create a key from the dashboard.
The full key is shown exactly once when it’s minted — Visceral stores only a
hash of it. By default the SDK reports to https://api.visceralai.dev; set
VISCERAL_BASE_URL to point at anything else.
Set up with Claude Code
The package ships a setup command, installed as visceral and also runnable
as python -m visceral:
It registers a /visceral skill with Claude Code
(in ~/.claude/skills, or in the current repo’s .claude/skills with
--project). Then open Claude Code in the repo you want instrumented and run
/visceral . to have it wire the SDK into your agent. visceral install --stdout prints the skill instead, for other assistants or manual setup.
Next: instrument your agent.
