{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Treasure Code","product_name":"Treasure Code","type":"markdown"},"seo":{"title":"Web Search Tool Setup Guide","description":"Learn how to add web search capabilities to AI Agent Foundry agents using the Web Search Tool with TDX CLI.","siteUrl":"https://docs.treasure.ai","lang":"en-US","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://www.treasure.ai/","name":"Treasure AI","url":"https://www.treasure.ai/","logo":"https://www.treasure.ai/hubfs/assets/images/logos/primary-logo.svg"},{"@type":"WebSite","@id":"https://docs.treasure.ai/#website","name":"Treasure AI Documentation","url":"https://docs.treasure.ai/","inLanguage":["en","ja"],"publisher":{"@id":"https://www.treasure.ai/"}}]},"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"web-search-tool-setup-guide","__idx":0},"children":["Web Search Tool Setup Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how to add web search capabilities to AI Agent Foundry agents."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ Experience creating and managing agents in AI Agent Foundry"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ TDX CLI installed and authenticated"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Limitation"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Web Search Tool is not visible in the console UI. Configuration is only possible via TDX CLI or Treasure Studio."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setup-flow","__idx":2},"children":["Setup Flow"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"1. Create Web Search Tool instance (API)\n   ↓\n2. Add tool to agent.yml (pull → edit → push)\n   ↓\n3. Test functionality\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-web-search-tool-instance","__idx":3},"children":["Step 1: Create Web Search Tool Instance"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-project-id","__idx":4},"children":["Get Project ID"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# List projects with IDs\ntdx llm project list --format json 2>&1 | tail -n +2 | jq -r '.[] | {id, name}'\n\n# Or store in variable\nPROJECT_ID=\"<your-project-id>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-web-search-tool","__idx":5},"children":["Create Web Search Tool"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cat > web_search_tool.json <<EOF\n{\n  \"data\": {\n    \"type\": \"webSearchTools\",\n    \"attributes\": {\n      \"name\": \"my_web_search_tool\",\n      \"projectId\": \"$PROJECT_ID\",\n      \"modelType\": \"gpt-5-mini\",\n      \"systemPrompt\": \"You are a focused web search assistant. Answer only with the information requested.\",\n      \"searchContextSize\": \"medium\",\n      \"filters\": {\n        \"allowed_domains\": [\n          \"example.com\",\n          \"openai.com\"\n        ]\n      }\n    }\n  }\n}\nEOF\n\ntdx api -X POST --type llm \\\n  -H \"Content-Type: application/vnd.api+json\" \\\n  -f web_search_tool.json \\\n  /api/web_search_tools\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.id"]}," from the response"]}," for later direct API calls (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]},") and verification. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent.yml"]}," example in this guide refers to the tool by name."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-add-to-agentyml","__idx":6},"children":["Step 2: Add to agent.yml"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pull-existing-agent","__idx":7},"children":["Pull Existing Agent"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Pull agent configuration\ntdx agent pull \"Project Name\" -y\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"edit-agentyml","__idx":8},"children":["Edit agent.yml"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agents/Project Name/agent-name/agent.yml"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"tools:\n  - type: web_search\n    target: '@ref(type: \"web_search_tool\", name: \"my_web_search_tool\")'\n    target_function: SEARCH\n    function_name: search_web\n    function_description: Search the web for current information\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key points:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}," name must match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attributes.name"]}," from Step 1"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["function_description"]}," guides the LLM's tool selection decisions"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"apply-changes","__idx":9},"children":["Apply Changes"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tdx agent push \"agents/Project Name/\" -y\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-test","__idx":10},"children":["Step 3: Test"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tdx chat --agent \"Project Name/agent-name\" \\\n  --new \"What is the latest news about Anthropic?\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Success if web search executes and returns current information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration-reference","__idx":11},"children":["Configuration Reference"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"web-search-tool-settings","__idx":12},"children":["Web Search Tool Settings"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tool name (referenced in @ref)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["projectId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Project ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["modelType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gpt-5-mini"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemPrompt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["System prompt for web search"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchContextSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["medium"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["low"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["medium"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["high"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userLocation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["❌"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Location object for regional optimization"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.allowed_domains"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed domain list (max 20, no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://"]},"). If you include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]},", you must include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowed_domains"]},"; an empty array (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]},") is allowed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"userlocation-example","__idx":13},"children":["userLocation Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"userLocation\": {\n  \"type\": \"approximate\",\n  \"country\": \"JP\",\n  \"city\": \"Minato\",\n  \"region\": \"Tokyo\",\n  \"timezone\": \"Asia/Tokyo\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"agentyml-tools-configuration","__idx":14},"children":["agent.yml Tools Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["web_search"]}," (fixed)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@ref(type: \"web_search_tool\", name: \"...\")"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target_function"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SEARCH"]}," (fixed)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["function_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Function name shown to LLM"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["function_description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Function description shown to LLM"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cost-optimization","__idx":15},"children":["Cost Optimization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To reduce costs:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["modelType"]},": Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gpt-5-mini"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["searchContextSize"]},": Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["low"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["medium"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["high"]}," is expensive)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["allowed_domains"]},": Restrict to trusted domains only"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["systemPrompt"]},": Include instructions for concise responses"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cat > update.json <<EOF\n{\n  \"data\": {\n    \"type\": \"webSearchTools\",\n    \"attributes\": {\n      \"modelType\": \"gpt-5-mini\",\n      \"searchContextSize\": \"low\"\n    }\n  }\n}\nEOF\n\ntdx api -X PATCH --type llm \\\n  -H \"Content-Type: application/vnd.api+json\" \\\n  -f update.json \\\n  /api/web_search_tools/<TOOL_ID>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":16},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"web-search-not-executing","__idx":17},"children":["Web search not executing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cause:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Web Search Tool feature not enabled for account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Web Search Tool instance doesn't exist"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Verify Web Search Tool exists\ntdx api --type llm /api/web_search_tools | jq '.data[] | {id, name, projectId}'\n\n# Contact Support for feature enablement\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"allowed_domains-settings-not-applied","__idx":18},"children":["allowed_domains settings not applied"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cause:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://"]}," in domain names"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding subdomains individually"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Specify domain only: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openai.com"]}," (not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://openai.com"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subdomains are automatically allowed (no need to add separately)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"higher-costs-than-expected","__idx":19},"children":["Higher costs than expected"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cause:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchContextSize: high"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["See \"Cost Optimization\" section above"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"content-type-error-http-415","__idx":20},"children":["Content-Type error (HTTP 415)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cause:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/vnd.api+json"]}," header in API call"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Required: include the Content-Type header\ntdx api -X POST --type llm \\\n  -H \"Content-Type: application/vnd.api+json\" \\\n  -f payload.json \\\n  /api/web_search_tools\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-reference","__idx":21},"children":["API Reference"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"web-search-tool-operations","__idx":22},"children":["Web Search Tool Operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["List all:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tdx api --type llm /api/web_search_tools\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get details:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tdx api --type llm /api/web_search_tools/<TOOL_ID>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tdx api -X PATCH --type llm \\\n  -H \"Content-Type: application/vnd.api+json\" \\\n  -f update.json \\\n  /api/web_search_tools/<TOOL_ID>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"tdx api -X DELETE --type llm /api/web_search_tools/<TOOL_ID>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-agent-tools","__idx":23},"children":["Verify Agent Tools"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Check tools attached to agent\ntdx api --type llm /api/agents/<AGENT_ID> | jq '.data.attributes.tools'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Expected output:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"toolTargetId\": \"<WEB_SEARCH_TOOL_ID>\",\n    \"targetFunction\": \"SEARCH\",\n    \"functionName\": \"search_web\",\n    \"functionDescription\": \"Search the web for current information\",\n    \"toolTargetType\": \"WebSearchTool\"\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"faq","__idx":24},"children":["FAQ"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Q: How to add to new project/agent?"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A: After creating project, create Web Search Tool with new project ID in Step 1. For agent creation, use API with explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["projectId"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cat > agent.json <<EOF\n{\n  \"data\": {\n    \"type\": \"agents\",\n    \"attributes\": {\n      \"name\": \"new-agent\",\n      \"projectId\": \"$PROJECT_ID\",\n      \"systemPrompt\": \"Your prompt here\",\n      \"modelType\": \"claude-4.5-sonnet\"\n    }\n  }\n}\nEOF\n\ntdx api -X POST --type llm \\\n  -H \"Content-Type: application/vnd.api+json\" \\\n  -f agent.json \\\n  /api/agents\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Q: Correct Claude model name format?"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claude-4.5-sonnet"]}," (note hyphens and periods)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Q: Using multiple tools together?"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A: Add multiple tool definitions under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tools:"]}," in agent.yml:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"tools:\n  - type: knowledge_base\n    target: '@ref(type: \"knowledge_base\", name: \"product-catalog\")'\n    target_function: SEARCH\n    function_name: search_products\n    function_description: Search internal product catalog\n\n  - type: web_search\n    target: '@ref(type: \"web_search_tool\", name: \"my_web_search_tool\")'\n    target_function: SEARCH\n    function_name: search_web\n    function_description: Search the web for current information\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Document Version:"]}," v2.1"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Last Updated:"]}," 2026-03-16"]}]},"headings":[{"value":"Web Search Tool Setup Guide","id":"web-search-tool-setup-guide","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Setup Flow","id":"setup-flow","depth":2},{"value":"Step 1: Create Web Search Tool Instance","id":"step-1-create-web-search-tool-instance","depth":2},{"value":"Get Project ID","id":"get-project-id","depth":3},{"value":"Create Web Search Tool","id":"create-web-search-tool","depth":3},{"value":"Step 2: Add to agent.yml","id":"step-2-add-to-agentyml","depth":2},{"value":"Pull Existing Agent","id":"pull-existing-agent","depth":3},{"value":"Edit agent.yml","id":"edit-agentyml","depth":3},{"value":"Apply Changes","id":"apply-changes","depth":3},{"value":"Step 3: Test","id":"step-3-test","depth":2},{"value":"Configuration Reference","id":"configuration-reference","depth":2},{"value":"Web Search Tool Settings","id":"web-search-tool-settings","depth":3},{"value":"userLocation Example","id":"userlocation-example","depth":3},{"value":"agent.yml Tools Configuration","id":"agentyml-tools-configuration","depth":3},{"value":"Cost Optimization","id":"cost-optimization","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Web search not executing","id":"web-search-not-executing","depth":3},{"value":"allowed_domains settings not applied","id":"allowed_domains-settings-not-applied","depth":3},{"value":"Higher costs than expected","id":"higher-costs-than-expected","depth":3},{"value":"Content-Type error (HTTP 415)","id":"content-type-error-http-415","depth":3},{"value":"API Reference","id":"api-reference","depth":2},{"value":"Web Search Tool Operations","id":"web-search-tool-operations","depth":3},{"value":"Verify Agent Tools","id":"verify-agent-tools","depth":3},{"value":"FAQ","id":"faq","depth":2}],"frontmatter":{"seo":{"title":"Web Search Tool Setup Guide","description":"Learn how to add web search capabilities to AI Agent Foundry agents using the Web Search Tool with TDX CLI."}},"lastModified":"2026-04-17T10:13:33.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/treasure-code/guide/web-search-tool","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}