Extend your agents with custom functionality. Middleware provides a powerful way for services to inject tools or override AI SDK functionality, enabling seamless integration of external services and custom behavior in your agents.

Key Features

• Tool Injection: Dynamically add tools to agents from external services
• AI SDK Override: Customize how AI SDK methods behave
• Service Integration: Connect agents with external platforms and APIs
• Extensible Architecture: Build reusable middleware components

Getting Started

Basic Middleware Implementation

Create a simple logging middleware:

Agent Integration

Add middleware to your agent through the services parameter:

Middleware Methods

Pre-processing Hooks

beforeStreamText(params: StreamTextParams): Promise<StreamTextParams>
Called before streamText executes. Modify parameters or add context before AI processing.

beforeGenerateText(params: GenerateTextParams): Promise<GenerateTextParams>
Called before generateText executes. Transform input parameters or inject additional context.

beforeGenerateObject(params: GenerateObjectParams): Promise<GenerateObjectParams>
Called before generateObject executes. Modify schema or parameters before structured generation.

Post-processing Hooks

afterStreamText(result: StreamTextResult, params: StreamTextParams): Promise<StreamTextResult>
Called after streamText completes. Transform results or log completion data.

afterGenerateText(result: GenerateTextResult, params: GenerateTextParams): Promise<GenerateTextResult>
Called after generateText completes. Modify the final result or perform cleanup.

afterGenerateObject(result: GenerateObjectResult, params: GenerateObjectParams): Promise<GenerateObjectResult>
Called after generateObject completes. Transform structured output or validate results.

Tool and Context Injection

injectTools(existingTools: Record<string, any>): Promise<Record<string, any>>
Add new tools to the agent's available tool set. Merge with existing tools.

injectContext(messages: any[], context: AgentContext): Promise<any[]>
Modify or enhance the message array before AI processing. Add system messages or context.

Examples

Tool Injection Middleware

Context Enhancement Middleware

Response Transformation Middleware

Multiple Middleware Composition

Error Handling

Best Practices

Middleware Ordering

Apply middleware in logical order - each middleware processes in sequence:

Keep Middleware Focused

Each middleware should have a single responsibility:

External Service Integration

For complex integrations like toolbox services, see the Toolbox Service implementation as an example of middleware usage.

Next Steps

• Sessions - Learn how middleware integrates with session management
• AI SDK - Explore AI SDK integration patterns
• Platform Services - Connect middleware with platform services

Middleware provides a clean way to extend agent functionality without modifying core agent logic, enabling better separation of concerns and reusable components.