docs: sync Haystack API reference on Docusaurus

docs-website/reference/haystack-api/tools_api.md

@@ -6,6 +6,190 @@ slug: "/tools-api"
 ---
 
 
+## agent_tool
+
+### agent_result_to_string
+
+```python
+agent_result_to_string(result: dict[str, Any]) -> str
+```
+
+Default `outputs_to_string` handler
+
+### AgentTool
+
+Bases: <code>ComponentTool</code>
+
+A Tool that wraps a Haystack Agent, allowing it to be used as a tool by another Agent.
+
+AgentTool is a building block for multi-agent systems: an Agent specialized in one task becomes a tool that
+other Agents can delegate to. The calling Agent only sees the final reply, so all the steps the wrapped Agent
+takes stay out of its context. Sensible defaults make this work out of the box: the task is delegated as a
+single user message and comes back as text.
+
+To use AgentTool, you first need a Haystack Agent. Below is an example of creating an AgentTool from an Agent
+that searches the web with a SerperDevWebSearch component from the `serperdev-haystack` integration package
+(`pip install serperdev-haystack`).
+
+## Usage Example:
+
+<!-- test-ignore -->
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools import AgentTool, ComponentTool
+from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
+
+researcher = Agent(
+    chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-mini"),
+    system_prompt="You are a research specialist. Investigate the task and report your findings.",
+    tools=[
+        ComponentTool(
+            component=SerperDevWebSearch(
+                top_k=3,
+            ),
+            name="web_search",
+            description="Search the web for current information on any topic",
+        ),
+    ],
+)
+
+research = AgentTool(
+    agent=researcher,
+    name="research",
+    description="Research a question on the web and report the findings",
+)
+
+coordinator = Agent(
+    chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
+    tools=[research],
+    system_prompt="You coordinate specialists. Delegate research questions, then answer the user.",
+)
+
+result = coordinator.run([ChatMessage.from_user("What are the latest developments in the Haystack framework?")])
+print(result["last_message"].text)
+```
+
+#### __init__
+
+```python
+__init__(
+    agent: Agent,
+    *,
+    name: str,
+    description: str,
+    parameters: dict[str, Any] | None = None,
+    outputs_to_string: dict[str, str | Callable[[Any], str]] | None = None,
+    inputs_from_state: dict[str, str] | None = None,
+    outputs_to_state: dict[str, dict[str, str | Callable]] | None = None
+) -> None
+```
+
+Create a Tool instance from a Haystack Agent.
+
+**Parameters:**
+
+- **agent** (<code>Agent</code>) – The Haystack Agent to wrap as a tool.
+- **name** (<code>str</code>) – Name of the tool.
+- **description** (<code>str</code>) – Description of the tool. It should tell the calling LLM what the Agent is specialized in
+  and when to delegate to it.
+- **parameters** (<code>dict\[str, Any\] | None</code>) – A JSON schema defining the parameters expected by the Tool.
+  Will fall back to a schema with the task to delegate as a single user message, plus one string parameter
+  for every other mandatory input of the Agent, if not provided.
+- **outputs_to_string** (<code>dict\[str, str | Callable\\[[Any\], str\]\] | None</code>) – Optional dictionary defining how tool outputs should be converted into string(s) or results.
+  If not provided, the tool result is the text of the Agent's final reply, or the serialized message if
+  the reply has no text. A warning is appended if the Agent stopped because it reached `max_agent_steps`.
+
+`outputs_to_string` supports two formats:
+
+1. Single output format - use "source", "handler", and/or "raw_result" at the root level:
+
+   ```python
+   {
+       "source": "last_message", "handler": format_reply, "raw_result": False
+   }
+   ```
+
+   - `source`: If provided, only the specified output key is sent to the handler.
+   - `handler`: A function that takes the tool output (or the extracted source value) and returns the
+     final result.
+   - `raw_result`: If `True`, the result is returned raw without string conversion, but applying the
+     `handler` if provided. This is intended for tools that return images. In this mode, the `handler`
+     is required, since the Agent returns a dictionary, and it must return a list of
+     `TextContent`/`ImageContent` objects to ensure compatibility with Chat Generators.
+
+1. Multiple output format - map keys to individual configurations:
+
+   ```python
+   {
+       "reply": {"source": "last_message", "handler": format_reply},
+       "steps": {"source": "step_count", "handler": str}
+   }
+   ```
+
+   Each key maps to a dictionary that can contain "source" and/or "handler".
+   Note that `raw_result` is not supported in the multiple output format.
+
+- **inputs_from_state** (<code>dict\[str, str\] | None</code>) – Optional dictionary mapping the calling Agent's state keys to Agent input names.
+  Example: `{"subject": "topic"}` maps state's "subject" to the Agent's "topic" input.
+  Inputs mapped this way are not added to the generated `parameters` schema, since the calling Agent
+  provides them.
+- **outputs_to_state** (<code>dict\[str, dict\[str, str | Callable\]\] | None</code>) – Optional dictionary defining how tool outputs map to keys within state as well as optional handlers.
+  The keys must be declared in the `state_schema` of the calling Agent.
+  Handlers merge the tool output into the state and are called as `handler(current_value, tool_output)`.
+  If the source is provided only the specified output key is sent to the handler.
+  Example:
+
+```python
+{
+    "notes": {"source": "last_message", "handler": custom_handler}
+}
+```
+
+If the source is omitted the whole tool result is sent to the handler.
+Example:
+
+```python
+{
+    "notes": {"handler": custom_handler}
+}
+```
+
+**Raises:**
+
+- <code>TypeError</code> – If the object passed is not a Haystack Agent instance.
+- <code>ValueError</code> – If `parameters` is provided but does not cover all the mandatory inputs of the Agent.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the AgentTool to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – The serialized dictionary representation of AgentTool.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> AgentTool
+```
+
+Deserializes the AgentTool from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary representation of AgentTool.
+
+**Returns:**
+
+- <code>AgentTool</code> – The deserialized AgentTool instance.
+
 ## component_tool
 
 ### ComponentTool