Sync Haystack API reference on Docusaurus (#10009)

Co-authored-by: vblagoje <458335+vblagoje@users.noreply.github.com>

Author: HaystackBot

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

@@ -26,22 +26,67 @@ When you call an Agent without tools, it acts as a ChatGenerator, produces one r
 from haystack.components.agents import Agent
 from haystack.components.generators.chat import OpenAIChatGenerator
 from haystack.dataclasses import ChatMessage
-from haystack.tools.tool import Tool
-
-tools = [Tool(name="calculator", description="..."), Tool(name="search", description="...")]
-
+from haystack.tools import Tool
+
+# Tool functions - in practice, these would have real implementations
+def search(query: str) -> str:
+    '''Search for information on the web.'''
+    # Placeholder: would call actual search API
+    return "In France, a 15% service charge is typically included, but leaving 5-10% extra is appreciated."
+
+def calculator(operation: str, a: float, b: float) -> float:
+    '''Perform mathematical calculations.'''
+    if operation == "multiply":
+        return a * b
+    elif operation == "percentage":
+        return (a / 100) * b
+    return 0
+
+# Define tools with JSON Schema
+tools = [
+    Tool(
+        name="search",
+        description="Searches for information on the web",
+        parameters={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "The search query"}
+            },
+            "required": ["query"]
+        },
+        function=search
+    ),
+    Tool(
+        name="calculator",
+        description="Performs mathematical calculations",
+        parameters={
+            "type": "object",
+            "properties": {
+                "operation": {"type": "string", "description": "Operation: multiply, percentage"},
+                "a": {"type": "number", "description": "First number"},
+                "b": {"type": "number", "description": "Second number"}
+            },
+            "required": ["operation", "a", "b"]
+        },
+        function=calculator
+    )
+]
+
+# Create and run the agent
 agent = Agent(
     chat_generator=OpenAIChatGenerator(),
-    tools=tools,
-    exit_conditions=["search"],
+    tools=tools
 )
 
-# Run the agent
 result = agent.run(
-    messages=[ChatMessage.from_user("Find information about Haystack")]
+    messages=[ChatMessage.from_user("Calculate the appropriate tip for an €85 meal in France")]
 )
 
-assert "messages" in result  # Contains conversation history
+# The agent will:
+# 1. Search for tipping customs in France
+# 2. Use calculator to compute tip based on findings
+# 3. Return the final answer with context
+print(result["messages"][-1].text)
 ```
 
 <a id="agent.Agent.__init__"></a>