Middleware

Agent middleware system.

Allows extension without bloating the core API.

class agent.middleware.Middleware[source]

Bases: object

Base middleware class.

Implement before(), after(), and/or on_error() to hook into the request lifecycle.

before(request)[source]

Called before the request is sent to the provider.

Can modify the request or return a new one.

Parameters:

request (AgentRequest)

Return type:

AgentRequest

after(request, response)[source]

Called after receiving a response from the provider.

Can modify the response or return a new one.

Parameters:
Return type:

AgentResponse

on_error(request, error)[source]

Called when an error occurs.

Return None to suppress the error, or return the error (modified or not).

Parameters:
Return type:

Exception | None

class agent.middleware.LoggingMiddleware(log_fn=None)[source]

Bases: Middleware

Simple logging middleware.

Parameters:

log_fn (Any)

before(request)[source]

Called before the request is sent to the provider.

Can modify the request or return a new one.

Parameters:

request (AgentRequest)

Return type:

AgentRequest

after(request, response)[source]

Called after receiving a response from the provider.

Can modify the response or return a new one.

Parameters:
Return type:

AgentResponse

on_error(request, error)[source]

Called when an error occurs.

Return None to suppress the error, or return the error (modified or not).

Parameters:
Return type:

Exception

class agent.middleware.MetricsMiddleware[source]

Bases: Middleware

Middleware that collects basic metrics.

before(request)[source]

Called before the request is sent to the provider.

Can modify the request or return a new one.

Parameters:

request (AgentRequest)

Return type:

AgentRequest

after(request, response)[source]

Called after receiving a response from the provider.

Can modify the response or return a new one.

Parameters:
Return type:

AgentResponse

on_error(request, error)[source]

Called when an error occurs.

Return None to suppress the error, or return the error (modified or not).

Parameters:
Return type:

Exception

stats()[source]

Get collected metrics.

Return type:

dict[str, Any]

class agent.middleware.RedactionMiddleware(patterns=None)[source]

Bases: Middleware

Middleware that redacts sensitive information from logs/traces.

Parameters:

patterns (list[str] | None)

before(request)[source]

Called before the request is sent to the provider.

Can modify the request or return a new one.

Parameters:

request (AgentRequest)

Return type:

AgentRequest

after(request, response)[source]

Called after receiving a response from the provider.

Can modify the response or return a new one.

Parameters:
Return type:

AgentResponse

class agent.middleware.RetryPolicyMiddleware(max_retries=3, retryable_errors=None)[source]

Bases: Middleware

Middleware that applies custom retry policies.

Parameters:
on_error(request, error)[source]

Called when an error occurs.

Return None to suppress the error, or return the error (modified or not).

Parameters:
Return type:

Exception | None

class agent.middleware.MiddlewareChain(middlewares=None)[source]

Bases: object

Chain of middleware to be executed in order.

Parameters:

middlewares (list[Middleware] | None)

add(middleware)[source]

Add a middleware to the chain.

Parameters:

middleware (Middleware)

Return type:

MiddlewareChain

run_before(request)[source]

Run all before hooks.

Parameters:

request (AgentRequest)

Return type:

AgentRequest

run_after(request, response)[source]

Run all after hooks in reverse order.

Parameters:
Return type:

AgentResponse

run_on_error(request, error)[source]

Run all error hooks.

Parameters:
Return type:

Exception | None