Skip to main content
Use the Pylva callback when LangGraph is your orchestration layer and you want cost attribution by graph node and end customer. For the difference between provider auto-instrumentation, callbacks, and manual reporting, see Supported Integrations.

Python

Pylva reads LangChain usage metadata at callback time. It sends model, provider, tokens in, tokens out, latency, status, LangGraph run ids, customer_id, and step_name. It does not send prompts, completions, tool arguments, or tool outputs.

TypeScript

@pylva/sdk/langchain re-exports the same TypeScript handler for LangChain.js callback discoverability. The deep entrypoints do not import the root SDK, so they do not auto-patch provider clients.

Node Attribution

LangGraph adds run metadata such as langgraph_node. Pylva uses that as the event step_name, so costs naturally group by graph node.
Step resolution order:
  • metadata["langgraph_node"]
  • metadata["pylva_step"]
  • metadata["langgraph_step"]
  • LangChain run name
Inside a graph, langgraph_node is set on every node run, so it always wins. Use pylva_step to label plain LangChain runs (no LangGraph) or runs where node metadata is absent:
Customer resolution order:
  • PylvaCallbackHandler(customer_id="...")
  • new PylvaCallbackHandler({ customerId: "..." }) in TypeScript
  • metadata["pylva_customer_id"]
  • metadata["customer_id"]
  • Active pylva.track_context
  • Active track() context in TypeScript
  • anonymous

Per-Customer Billing

Pass one stable opaque customer id per graph invocation.
Pylva prices usage on the server, so pricing changes do not require changing the graph code that reports raw usage.

Tool Calls

Tool-call billing is opt-in because many tools are not billable. Enable it only when a tool execution itself should create a configured usage event.
Tool events report metric="calls" and metric_value=1. Configure the price for that metric in Pylva before using it for invoices.

Avoid Double Counting

Use either the LangGraph callback path or the provider auto-instrumentation path for the same runtime. In TypeScript, importing @pylva/sdk/langgraph or @pylva/sdk/langchain alone does not auto-patch providers; importing the root @pylva/sdk package does.

Failure Behavior

Callback errors are swallowed. If Pylva is unavailable, the graph continues. When LangChain does not provide token usage, Pylva records the run with zero tokens and metadata.usage_missing=true rather than reading prompt text to estimate usage.