Middleware

​

Overview

• Agent lifecycle: Tracks when an agent starts and completes
• Model calls: Logs all LLM invocations with prompts, responses, and metadata
• Tool calls: Captures tool invocations including function names, arguments, and outputs
• Async support: Full support for both synchronous and asynchronous agent execution

​

Basic usage

1. An agent node is created to track the overall execution
2. Each model call creates an LLM node with prompt and response details
3. Each tool call creates a tool node with function name, arguments, and output
4. All nodes are linked hierarchically under the agent node

​

Configuration options

• splunk_ao_logger (optional): A custom SplunkAOLogger instance. If not provided, a default logger is created.
• start_new_trace (default: True): Whether to start a new trace on agent invocation. Set to False to add to an existing trace.
• flush_on_chain_end (default: True): Whether to flush logs to Splunk Agent Observability when the agent completes.
• ingestion_hook (optional): A callback function that receives TracesIngestRequest objects before they’re sent to Splunk Agent Observability.

​

Custom logger

from splunk_ao.logger import SplunkAOLogger

# Create a custom logger
logger = SplunkAOLogger(
    project_name="my-agent-project",
    console_output=True
)

# Use it with middleware
agent = create_agent(
    model,
    tools=[get_weather, get_stock_price],
    middleware=[SplunkAOMiddleware(splunk_ao_logger=logger)]
)

​

Trace management

​

Add to existing trace

# Create a logger and start a trace
logger = SplunkAOLogger()
session_id = logger.create_session()
trace_id = logger.create_trace(session_id)

# Create middleware that adds to existing trace
middleware = SplunkAOMiddleware(
    splunk_ao_logger=logger,
    start_new_trace=False
)

# The agent execution will be added to the existing trace
agent = create_agent(model, tools=[...], middleware=[middleware])
agent.invoke({"messages": [...]})

​

Manual flush control

# Disable automatic flushing
middleware = SplunkAOMiddleware(
    splunk_ao_logger=logger,
    flush_on_chain_end=False
)

# Execute multiple agent calls
agent.invoke({"messages": [...]})
agent.invoke({"messages": [...]})

# Manually flush when ready
logger.flush()

​

What gets logged

​

Agent node

• Input state (messages)
• Output state (final messages)
• Execution time

​

Model call nodes

• Model name and configuration (temperature, etc.)
• Input messages (including system message if present)
• Output response
• Tools available to the model
• Timing evaluators (start time, time to first token if available)

​

Tool call nodes

• Tool/function name
• Tool arguments (serialized)
• Tool output
• Execution time

​

Comparison with SplunkAOCallback

• You’re building LangGraph agents in Python
• You want automatic, drop-in logging
• You prefer simpler setup

• You need fine-grained control over logging
• You’re working with complex LangChain applications
• You want to log specific components selectively

​

Async support

# Async agent usage
async def main():
    agent = create_agent(
        model,
        tools=[get_weather, get_stock_price],
        middleware=[SplunkAOMiddleware()]
    )
    result = await agent.ainvoke({
        "messages": [HumanMessage(content="...")]
    })
    print(result)

​

Best practices

1. Use middleware for LangGraph agents: For LangGraph-based agents, middleware provides the simplest integration
2. Add meaningful metadata: Include relevant project and session information in your logger configuration
3. Configure flush behavior: For high-volume applications, consider disabling auto-flush and batch your logs
4. Share loggers: Use the same logger instance across middleware for unified trace management
5. Monitor execution: Review the hierarchical traces in Splunk Agent Observability to understand agent behavior

​

Example

​

Next steps

​

Related documentation

​

Cookbooks