استدعاء الأدوات ومستشارو الوكلاء

Large language models can reason over text, but they cannot fetch a live order status, query your database, or call a payment gateway on their own. Tool calling (also called function calling) bridges that gap.

• The model decides when a tool is needed based on the user's request.
• Spring AI invokes the matching Java method and feeds the result back into the conversation.
• The model then produces a grounded, final answer.

In Spring AI, a tool is just an ordinary Java method annotated with @Tool. The framework reads the method signature and JavaDoc-style description, generates a JSON schema, and exposes it to the model.

Annotate a method with @Tool and give it a clear description. The model uses that description to decide whether to call it, so write it as if you were instructing a junior developer.

• Use @ToolParam to describe individual arguments.
• Return types are serialized to JSON automatically.
• Keep the method deterministic and side-effect-aware.

Tools are attached per request through the fluent ChatClient API. Pass an instance whose annotated methods become callable tools for that exchange.

• .tools(Object...) registers one or more tool-bearing beans.
• The model may issue zero, one, or several tool calls before answering.
• Spring AI runs the full call loop transparently and returns the final text.

Understanding the loop is essential for C2-level work. When the model requests a tool, Spring AI does not return control to you by default; it executes the tool and continues the conversation automatically.

• The model returns an assistant message containing one or more tool call requests.
• Spring AI matches each request to a registered method and invokes it.
• Results are wrapped as tool response messages and appended to the prompt.
• The model is called again with the enriched context until it emits a normal text answer.

This default behavior is driven by the framework's ToolCallingManager.

Annotations are convenient, but sometimes you need tools defined at runtime or from a lambda. Use FunctionToolCallback to register a Function with an explicit name, description, and input type.

• The input type drives JSON schema generation.
• You stay in full control of serialization and naming.
• Useful for dynamically discovered capabilities.

Sometimes a tool's raw result should be returned straight to the caller without another model round-trip, for example when the tool already produced the final user-facing payload.

• Set returnDirect = true on @Tool to short-circuit the loop.
• The framework returns the tool result instead of feeding it back to the model.
• This saves tokens and latency but skips the model's natural-language framing.

Where tools extend what the model can do, advisors intercept and shape how each request and response flows. An advisor is a middleware in the ChatClient pipeline.

• Request advisors mutate the prompt before it reaches the model (inject context, retrieve documents, add system instructions).
• Response advisors post-process the model's output (logging, redaction, safety checks).
• Advisors are chained and ordered, much like servlet filters.

Spring AI ships several built-in advisors and lets you write your own by implementing the advisor interfaces.

Two of the most used built-in advisors:

• MessageChatMemoryAdvisor — injects prior conversation turns so the model has memory across requests, backed by a ChatMemory store.
• QuestionAnswerAdvisor — performs retrieval-augmented generation by querying a VectorStore and prepending relevant documents.

You register them on the builder so they apply to every call, or per-prompt for one-off behavior.

Implement CallAdvisor to participate in the synchronous call chain. The key method receives the request, calls chain.nextCall(...), and can transform the response.

• getName() identifies the advisor.
• getOrder() controls position; lower runs earlier on the request side.
• Wrap nextCall to add logging, timing, or content filtering.

Advisors form an ordered chain. Picture an onion: on the way in advisors run from lowest order to highest, and on the way out the responses unwind in reverse.

• A memory advisor with a low order injects history early so RAG and tools see it.
• A safety/redaction advisor often sits at a high order to inspect the final text last.
• Order ties are resolved by registration sequence; be explicit with getOrder() to avoid surprises.

Because tools and advisors both operate on the same prompt, design their interaction deliberately: advisors prepare context, tools fetch live data, and a final response advisor can sanitize the merged result.

Real agents combine both mechanisms in a single fluent call. Here the client carries default memory and RAG advisors, while a domain tool is attached for this request.

• Advisors enrich the prompt with history and retrieved knowledge.
• The model may still call the tool to obtain live, authoritative data.
• The result is an agent that remembers, grounds, and acts.

You now know how to extend models with callable Java code and compose request/response behavior:

• Tools are Java methods marked with @Tool (or built via FunctionToolCallback) that the model invokes to fetch data or act.
• Spring AI runs the tool call loop automatically; returnDirect = true short-circuits it.
• Advisors are pipeline middleware: request advisors enrich the prompt (memory, RAG), response advisors post-process output (logging, safety).
• Advisors are ordered and unwind like an onion; design tool/advisor interaction deliberately.
• Combine memory + RAG advisors with domain tools to build agents that remember, ground, and act.