---
name: spring-ai-alibaba-hooks-interceptors
description: Build, review, or explain Spring AI Alibaba hook and interceptor customizations for ReactAgent and related agent workflows. Use when requests mention ReactAgent.builder().hooks(...), .interceptors(...), MessagesModelHook, ModelHook, AgentHook, ModelInterceptor, ToolInterceptor, HumanInTheLoopHook, SummarizationHook, ModelCallLimitHook, ToolRetryInterceptor, TodoListInterceptor, ToolSelectionInterceptor, ToolEmulatorInterceptor, ContextEditingInterceptor, or when Codex must decide whether a behavior belongs in a hook or an interceptor.
---

# Spring AI Alibaba Hooks And Interceptors

Use this skill to implement or explain how Spring AI Alibaba customizes agent execution around `ReactAgent`. Read [references/hooks-interceptors.md](./references/hooks-interceptors.md) when exact built-in options, execution order, or API shapes matter.

## Workflow

1. Start from the control goal.
Classify the request as one of: observe, transform, enforce, limit, pause for approval, or short-circuit execution. Pick the extension point from that goal instead of starting from class names.

2. Choose the narrowest extension point that can solve the problem.
- Use `MessagesModelHook` for simple message-list changes before or after model calls.
- Use `ModelHook` when logic depends on `OverAllState`, custom state keys, or cross-call coordination.
- Use `AgentHook` when behavior belongs to overall agent start or finish.
- Use `ModelInterceptor` when wrapping or rewriting the model request or response.
- Use `ToolInterceptor` when wrapping, retrying, caching, monitoring, or rewriting tool execution.

3. Prefer built-ins before custom code.
Reach for the official implementations first: `SummarizationHook`, `HumanInTheLoopHook`, `ModelCallLimitHook`, `PIIDetectionHook`, `ToolRetryInterceptor`, `TodoListInterceptor`, `ToolSelectionInterceptor`, `ToolEmulatorInterceptor`, and `ContextEditingInterceptor`.

4. Keep each hook or interceptor single-purpose.
Compose several small units instead of one large class that does logging, moderation, retries, and prompt rewriting together.

5. Respect ordering rules.
`before*` hooks run in registration order, `after*` hooks run in reverse order, and interceptors wrap each other like nested middleware. Put broad outer concerns first and narrow inner concerns later.

## Selection Rules

- Need pause/resume, approval, or agent lifecycle control: use a `Hook`.
- Need request/response interception without resumable control flow: use an `Interceptor`.
- Need only message trimming, message filtering, or system-message injection: prefer `MessagesModelHook`.
- Need full state access, counters, shared state, or custom state updates: use `ModelHook`.
- Need behavior only at agent start/end: use `AgentHook`.
- Need dynamic tools, moderation, model-side logging, or response rewriting: use `ModelInterceptor`.
- Need tool retry, caching, failure wrapping, or per-tool telemetry: use `ToolInterceptor`.

## Implementation Defaults

- Prefer `MessagesModelHook` over `ModelHook` for message-only work. It is the recommended and simpler API.
- Use `RunnableConfig.context()` for transient counters and metrics shared within one agent run.
- Namespace custom context keys defensively, for example with double underscores such as `__model_call_count__`.
- Add a saver or checkpointer when using `HumanInTheLoopHook`; the official guide calls out that interrupted execution needs persisted state.
- Keep `ReactAgent` assembly in the service layer, not controllers, to stay aligned with this repository's Spring Boot structure.
- Read [references/hooks-interceptors.md](./references/hooks-interceptors.md) before inventing a custom class; an official built-in often already covers the need.

## Minimal Assembly Pattern

```java
ReactAgent agent = ReactAgent.builder()
    .name("my_agent")
    .model(chatModel)
    .tools(tools)
    .hooks(summarizationHook, modelCallLimitHook)
    .interceptors(toolRetryInterceptor, contextEditingInterceptor)
    .build();
```

## References

- Read [references/hooks-interceptors.md](./references/hooks-interceptors.md) for the extracted tutorial guidance on built-ins, custom extension points, execution order, and example patterns.
