agents.base.structured_output_handler

Structured output handler for clean extraction from LangGraph state.

This module provides utilities to handle LangGraph’s AddableValuesDict return type and extract structured output cleanly.

Classes

StructuredOutputHandler

Handler for extracting structured output from LangGraph results.

Functions

extract_structured_output(result, output_model[, ...])

Convenience function to extract structured output.

require_structured_output(result, output_model[, ...])

Extract structured output or raise error.

Module Contents

class agents.base.structured_output_handler.StructuredOutputHandler(output_model, field_name=None, common_fields=None)

Bases: Generic[T]

Handler for extracting structured output from LangGraph results.

This class provides a clean interface for working with LangGraph’s AddableValuesDict return type, making it easy to extract structured output from graph execution results.

Examples

Basic usage:

handler = StructuredOutputHandler(AnalysisResult)
result = await agent.arun(input_data)
analysis = handler.extract(result)

With custom field name:

handler = StructuredOutputHandler(
    AnalysisResult,
    field_name="custom_output"
)

With validation:

analysis = handler.extract_or_raise(result)
# Raises ValueError if not found

Initialize the handler.

Parameters:

  • output_model (type[T]) – The Pydantic model class for structured output

  • field_name (str | None) – Optional specific field name to extract

  • common_fields (list[str] | None) – Additional field names to check

extract(result)

Extract structured output from result.

This method handles various result types including AddableValuesDict, regular dicts, and objects with dict-like interfaces.

Parameters:

result (dict | langgraph.pregel.io.AddableValuesDict | Any) – The result from LangGraph execution

Returns:

The extracted structured output or None if not found

Return type:

T | None

extract_or_default(result, default=None)

Extract structured output or return default.

Parameters:

  • result (Any) – The result from LangGraph execution

  • default (T | None) – Default value to return if not found

Returns:

The extracted output or default value

Return type:

T | None

extract_or_raise(result)

Extract structured output or raise an error.

Parameters:

result (Any) – The result from LangGraph execution

Returns:

The extracted structured output

Raises:

ValueError – If structured output not found

Return type:

T

property expected_fields: list[str]

Get list of field names that will be searched.

Return type:

list[str]

agents.base.structured_output_handler.extract_structured_output(result, output_model, field_name=None)

Convenience function to extract structured output.

Parameters:

  • result (Any) – The result from LangGraph execution

  • output_model (type[T]) – The expected Pydantic model type

  • field_name (str | None) – Optional specific field name

Returns:

The extracted structured output or None

Return type:

T | None

Examples

Basic extraction:

analysis = extract_structured_output(result, AnalysisResult)

With field name:

output = extract_structured_output(
    result,
    CustomOutput,
    field_name="my_output"
)
agents.base.structured_output_handler.require_structured_output(result, output_model, field_name=None)

Extract structured output or raise error.

Parameters:

  • result (Any) – The result from LangGraph execution

  • output_model (type[T]) – The expected Pydantic model type

  • field_name (str | None) – Optional specific field name

Returns:

The extracted structured output

Raises:

ValueError – If output not found

Return type:

T

Examples

Require output:

analysis = require_structured_output(result, AnalysisResult)
# Raises ValueError if not found