Framework Integrations
Briefcase provides drop-in instrumentation for three AI frameworks. Pick the handler that matches your stack — or combine them.
Supported Frameworks
| Framework | Handler Class | Mechanism | Install Extra |
|---|---|---|---|
| LangChain | BriefcaseLangChainHandler | Callback handler (duck-typed) | base |
| OpenAI Agents SDK | OpenAIAgentsTracer | TracingProcessor via add_trace_processor | base |
| PageIndex | PageIndexTracer | SDK wrapper around PageIndexClient | pageindex |
| PageIndex via MCP | PageIndexMCPObserver | Post-processor for MCP tool call records | base |
What Each Handler Captures
BriefcaseLangChainHandler
| Event | decision_type | Key fields |
|---|---|---|
| LLM / Chat model call | llm | model name, prompts/messages, completion text, token usage |
| Chain execution | chain | chain class name, inputs, outputs |
| Tool invocation | tool | tool name, input string, output string |
| Retriever query | retriever | query string, retrieved documents (count + preview) |
OpenAIAgentsTracer
| Span type | type field | Key fields |
|---|---|---|
| Agent run | agent_run | agent_name, tools list, handoffs list, output_type |
| Tool call | tool_call | tool_name, input, output |
| Agent handoff | handoff | from_agent, to_agent |
| Guardrail evaluation | guardrail | guardrail_name, triggered |
| Model generation | generation | model, usage, input, output |
PageIndexTracer
| Attribute | Type | Description |
|---|---|---|
pageindex.doc_id | str | Document identifier passed to chat_completions |
pageindex.retrieval_method | str | Always "tree_search" |
pageindex.tree.depth | int | Maximum depth of the document tree |
pageindex.tree.nodes_visited | int | Total nodes in the tree (upper-bound proxy) |
pageindex.tree.path | str | Human-readable path summary: root > Section 1 > ... |
pageindex.tree.backtrack_count | int | Always 0 (server-side only) |
PageIndexMCPObserver
Adds the same pageindex.* attributes as PageIndexTracer by parsing the
JSON output of MCP tool calls. No pageindex package required.
Common Fields
All handlers produce records with these fields:
decision_id UUID string
started_at / ended_at ISO 8601 timestamps
execution_time_ms float
engagement_id project identifier (LangChain/PageIndex only)
workstream_id workflow identifier (LangChain/PageIndex only)
context_version optional version tag
error error message if the call failed
Choosing Between Handlers
Use BriefcaseLangChainHandler when your agent is built with LangChain
chains or agents. It automatically captures all nested events in a single
invocation — LLM calls, tool calls, and retrievers — with parent/child
span relationships.
Use OpenAIAgentsTracer when using the OpenAI Agents SDK directly.
It hooks into the global tracing layer so you don't need to thread callbacks
through every component.
Use PageIndexTracer when calling PageIndex directly (not as a LangChain
tool). It captures tree structure metadata unavailable from the LangChain tool
output.
Use PageIndexMCPObserver when an LLM agent calls PageIndex via MCP.
The observer post-processes the tool call record from A1 or A2 handlers to
add pageindex.* attributes.