LangChain API Reference (Python)

Method signatures, option types and extended log fields for the LangChain and LangGraph callback path. For a guide-level introduction, see LangChain.

langchain()

Returns a LangChain BaseCallbackHandler that you pass into callbacks. Async because LangChain is imported on demand. Create one callback per request so each request gets its own trace.

The callback is synchronous and works with both invoke() and ainvoke().

Signature


async def langchain(
    self,
    options: LangChainCallbackOptions | None = None,
) -> BaseCallbackHandler

Parameters

Name	Type	Default	Description
`options.role`	`str`	`'unspecified'`	Overrides the role set on `AiAccountability.init()` for this callback.
`options.trace_id`	`str`	auto	Custom trace id. Defaults to the root run’s `run_id`.
`options.on_error`	`Callable`	`None`	Called when an internal handler error occurs. If omitted, the error and its entry are dropped silently.

Returns

BaseCallbackHandler (awaitable factory).

Example


from sarek import AiAccountability, LangChainCallbackOptions
 
sarek = await AiAccountability.init(name='loan-desk')
callback = await sarek.langchain(
    LangChainCallbackOptions(
        role='credit-assessor',
        trace_id='request-2026-06-16-4821',
        on_error=lambda err, context: app_logger.error(
            'sarek callback error',
            extra={'handler': context['handler'], 'run_id': context['run_id']},
        ),
    )
)

langgraph()

Alias for langchain(). Use it for LangGraph apps; the callback behaves identically.

Signature


async def langgraph(
    self,
    options: LangChainCallbackOptions | None = None,
) -> BaseCallbackHandler

Event types

The callback logs five event types. The discriminator is event_type:

Event	Start handler	Input hash	Output hash
`llm`	chat model or legacy LLM start	the prompt messages or strings	the generated text
`tool`	tool start	the tool input	the tool output
`retriever`	retriever start	the query	document metadata only, never content
`chain`	chain start	the chain inputs	the chain outputs
`error`	LLM, tool or chain error	reused from the matching start	empty

Extended LogEntry fields

On top of the standard LogEntry fields, the callback path populates these:

Field	Source	Notes
`event_type`	the handler that fired	`llm`, `tool`, `retriever`, `chain` or `error`
`outcome`	the handler that fired	`success`, or `error` on a failed call
`trace_id`	the root run’s `run_id`	equals LangSmith’s `trace_id`; ties one request together
`run_id`	the callback’s run id for this event	unique per event
`parent_run_id`	the callback’s parent run id	`None` on the root; reconstructs the call tree
`chain_name`	the serialized chain id	`chain` events
`tool_name`	the tool name	`tool` events
`tool_call_id`	the model’s tool-call id	links a tool event to the call that requested it
`error_class`	the exception class name	`error` events
`error_hash`	SHA3-256 of the error message	the raw message is never stored
`model_params`	`configured` from the invocation params, `actual` from the result	`llm` events only; see below
`thread_id`	`metadata.thread_id`	LangGraph; `None` for plain LangChain
`langgraph_node`	`metadata.langgraph_node`	LangGraph; `None` otherwise
`langgraph_step`	`metadata.langgraph_step`	LangGraph; `None` otherwise
`checkpoint_ns`	`metadata.checkpoint_ns`	LangGraph; `None` otherwise
`tags`, `metadata`	passed through from the callback	carry deployer context, end-user id, jurisdiction

model_params: configured against actual

On llm events, model_params separates what you asked for from what the provider reported:

configured holds temperature, max_tokens and top_p, read from the invocation parameters LangChain builds for the call. These are the same values LangSmith logs.
actual holds the provider’s own output block, framed as what the provider actually reported. Many providers leave most of it empty, which is expected.

Retriever output is metadata only

For retriever events the output hash is computed over the id and source of each retrieved document, never the document content. The page content never leaves the SDK. If you need the content for retention, keep it yourself.

Fields that differ on this path

A few standard LogEntry fields do not carry their usual meaning when the entry comes from a callback:

Field	On the callback path
`prediction_id`	empty; LangChain does not surface a provider response id here
`citations`	not populated; this is a Perplexity-only field on the direct path
`status_code`	always `200`. Use `outcome` for success or failure, not the status code
`environment`	always `None` in Python