diff --git a/docs-website/reference/haystack-api/tools_api.md b/docs-website/reference/haystack-api/tools_api.md index bb95ca91dc..65eefb175c 100644 --- a/docs-website/reference/haystack-api/tools_api.md +++ b/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: ComponentTool + +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: + + + +```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** (Agent) – The Haystack Agent to wrap as a tool. +- **name** (str) – Name of the tool. +- **description** (str) – Description of the tool. It should tell the calling LLM what the Agent is specialized in + and when to delegate to it. +- **parameters** (dict\[str, Any\] | None) – 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** (dict\[str, str | Callable\\[[Any\], str\]\] | None) – 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** (dict\[str, str\] | None) – 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** (dict\[str, dict\[str, str | Callable\]\] | None) – 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:** + +- TypeError – If the object passed is not a Haystack Agent instance. +- ValueError – 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:** + +- dict\[str, Any\] – The serialized dictionary representation of AgentTool. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> AgentTool +``` + +Deserializes the AgentTool from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary representation of AgentTool. + +**Returns:** + +- AgentTool – The deserialized AgentTool instance. + ## component_tool ### ComponentTool