From dd62a2388cf1a701af164ccc207a32c00e063f41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?AN=20YU=20=28=E5=AE=89=E5=AE=87=29?=
 <33403629+anyuzoey@users.noreply.github.com>
Date: Fri, 18 Apr 2025 01:20:52 +0100
Subject: [PATCH] docs: add notes to websearch tool and two extra example
 scripts (#1354)

# What does this PR do?

- Adds a note about unexpected Brave Search output appearing even when
Tavily Search is called. This behavior is expected for now and is a work
in progress https://github.com/meta-llama/llama-stack/issues/1229. The
note aims to clear any confusion for new users.
- Adds two example scripts demonstrating how to build an agent using:
    1. WebSearch tool
    2. WolframAlpha tool
These examples provide new users with an instant understanding of how to
integrate these tools.

[//]: # (If resolving an issue, uncomment and update the line below)
[//]: # (Closes #[issue-number])

## Test Plan
Tested these example scripts using following steps:
step 1. `ollama run llama3.2:3b-instruct-fp16 --keepalive 60m`
step 2.
```
export INFERENCE_MODEL="meta-llama/Llama-3.2-3B-Instruct"
export LLAMA_STACK_PORT=8321
```
step 3: `llama stack run --image-type conda
~/llama-stack/llama_stack/templates/ollama/run.yaml`
step 4: run the example script with your api keys.

expected output:

![image](https://github.com/user-attachments/assets/308ddb17-a087-4cf2-8622-b085174ea0ab)

![image](https://github.com/user-attachments/assets/639f239f-8966-433d-943c-ee6b304c0d71)


[//]: # (## Documentation)
---
 docs/source/building_applications/tools.md | 64 +++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/docs/source/building_applications/tools.md b/docs/source/building_applications/tools.md
index 94841a773..fc2dd08e5 100644
--- a/docs/source/building_applications/tools.md
+++ b/docs/source/building_applications/tools.md
@@ -41,7 +41,7 @@ client.toolgroups.register(
 
 The tool requires an API key which can be provided either in the configuration or through the request header `X-LlamaStack-Provider-Data`. The format of the header is `{"<provider_name>_api_key": <your api key>}`.
 
-
+> **NOTE:** When using Tavily Search and Bing Search, the inference output will still display "Brave Search." This is because Llama models have been trained with Brave Search as a built-in tool. Tavily and bing is just being used in lieu of Brave search.
 
 #### Code Interpreter
 
@@ -214,3 +214,65 @@ response = agent.create_turn(
     session_id=session_id,
 )
 ```
+## Simple Example 2: Using an Agent with the Web Search Tool
+1. Start by registering a Tavily API key at [Tavily](https://tavily.com/). 
+2. [Optional] Provide the API key directly to the Llama Stack server
+```bash
+export TAVILY_SEARCH_API_KEY="your key"
+```
+```bash
+--env TAVILY_SEARCH_API_KEY=${TAVILY_SEARCH_API_KEY}
+```
+3. Run the following script.
+```python
+from llama_stack_client.lib.agents.agent import Agent
+from llama_stack_client.types.agent_create_params import AgentConfig
+from llama_stack_client.lib.agents.event_logger import EventLogger
+from llama_stack_client import LlamaStackClient
+
+client = LlamaStackClient(
+    base_url=f"http://localhost:8321",
+    provider_data = {"tavily_search_api_key": "your_TAVILY_SEARCH_API_KEY"}  # Set this from the client side. No need to provide it if it has already been configured on the Llama Stack server.
+    )   
+
+agent = Agent(
+    client, 
+    model="meta-llama/Llama-3.2-3B-Instruct",
+    instructions=(
+        "You are a web search assistant, must use websearch tool to look up the most current and precise information available. "
+    ),
+    tools=["builtin::websearch"], 
+    )
+
+session_id = agent.create_session("websearch-session")
+
+response = agent.create_turn(
+    messages=[{"role": "user", "content": "How did the USA perform in the last Olympics?"}],
+    session_id=session_id,
+)
+for log in EventLogger().log(response):
+    log.print()
+```
+
+## Simple Example3: Using an Agent with the WolframAlpha Tool
+1. Start by registering for a WolframAlpha API key at [WolframAlpha Developer Portal](https://developer.wolframalpha.com/access).
+2. Provide the API key either when starting the Llama Stack server:
+    ```bash
+    --env WOLFRAM_ALPHA_API_KEY=${WOLFRAM_ALPHA_API_KEY}
+    ```
+    or from the client side:
+    ```python
+    client = LlamaStackClient(
+        base_url="http://localhost:8321",
+        provider_data={"wolfram_alpha_api_key": wolfram_api_key}
+    )
+    ```
+3. Configure the tools in the Agent by setting `tools=["builtin::wolfram_alpha"]`.
+4. Example user query:
+    ```python
+    response = agent.create_turn(
+         messages=[{"role": "user", "content": "Solve x^2 + 2x + 1 = 0 using WolframAlpha"}],
+         session_id=session_id,
+    )
+    ```
+```
\ No newline at end of file