Instrument your agent

Your agent already produces everything worth recording — model calls, tool calls, node boundaries, human waits, failures. The framework throws it away. The SDK keeps it.

Custom agents

An agent you wrote yourself, or one not listed here.

LangChain and LangGraph

Graphs, nodes, tools, retrievers, models.

CrewAI

Crews, flows, agents by role, tools.

LlamaIndex

Workflows, steps, function agents, retrievers.

Pydantic AI

Typed agents, capabilities, tools, retries.

Before you start

Two things this path assumes, neither of which the code below does for you:

Requirement	Why
Python 3.10 or newer	The floor the SDK declares.
A machine set up with `failproofai config`	That command installs the failproofaid daemon, and the daemon is the only thing that ships what the SDK writes. Without it the batches pile up in the spool directory and never leave.

This path records; it does not enforce. The SDK captures what your agent did. Policies fire from a hook inside an agent CLI, so enforcing on a framework agent means putting a hook in your own runtime — see Policies.

Three lines, whichever framework

pip install 'failproofai-sdk[langgraph]'

pip install 'failproofai-sdk[crewai]'

pip install 'failproofai-sdk[llamaindex]'

pip install 'failproofai-sdk[pydantic-ai]'

pip install failproofai-sdk

import failproofai_sdk

failproofai_sdk.configure(environment="production")
failproofai_sdk.instrument()          # detects the frameworks you imported

with failproofai_sdk.session():
    ...                               # your existing agent call, unchanged

No decorators on your functions, no callback passed to your calls, no ids threaded through your code. Only the call inside the session differs:

LangGraph
CrewAI
LlamaIndex
Pydantic AI
Custom agents

graph.invoke({"messages": [HumanMessage("...")]})

Crew(agents=[analyst, writer], tasks=[gather, summarise]).kickoff()

await agent.run("...")        # under `async with failproofai_sdk.session():`

agent.run_sync("...")

with failproofai_sdk.agent("planner"):
    with failproofai_sdk.tool_call("search", input={"q": q}) as t:
        t.output = search(q)

The extra installs the framework. Every adapter ships in the base wheel, so a project that already has its framework needs no extra at all.

Check it arrived

Run one instrumented session, then open Observe → Sessions and select your environment. The run appears as a reconstructed trace. If nothing arrives, confirm the machine is set up and connected with failproofai config --status. If it is not, run failproofai config. See Choose your setup.

Do not check the spool directory to confirm delivery. The Failproof daemon collects and deletes each batch within milliseconds, so reading it races the collector and shows far fewer events than were emitted.

To prove the SDK is writing at all, stop the daemon first, then run your session and look in ~/.failproofai/custom-agents/events/. With the daemon running, an empty directory is the healthy state.

sudo systemctl stop failproofaid@$USER

sudo launchctl bootout system/ai.failproof.failproofaid.$USER

Run failproofai config afterwards to put it back. While the daemon is stopped, hook events on this machine have no evaluator and are denied, so stop it only for as long as the check takes.

Each quickstart above links to its full guide — what gets recorded, options, streaming, span naming, and the problems people actually hit. They live under Trace Agents → Plug in your agent.

How it works

The data model, the ids, the event types, and how events reach Cloud.

Read a trace

Follow causality through a session instead of disconnected logs.

Find your first failure

Audit the sessions you just captured.

Understand every run

Plug in your agent

Custom agents

LangChain and LangGraph

CrewAI

LlamaIndex

Pydantic AI

Before you start

Three lines, whichever framework

Check it arrived

Next

How it works

Read a trace

Find your first failure

Custom agents

LangChain and LangGraph

CrewAI

LlamaIndex

Pydantic AI

​Before you start

​Three lines, whichever framework

​Check it arrived

​Next

How it works

Read a trace

Find your first failure

Before you start

Three lines, whichever framework

Check it arrived

Next