# Web Search Tool Setup Guide

This guide explains how to add web search capabilities to AI Agent Foundry agents.

## Prerequisites

- ✅ Experience creating and managing agents in AI Agent Foundry
- ✅ TDX CLI installed and authenticated


Limitation
Web Search Tool is not visible in the console UI. Configuration is only possible via TDX CLI or Treasure Studio.

## Setup Flow


```
1. Create Web Search Tool instance (API)
   ↓
2. Add tool to agent.yml (pull → edit → push)
   ↓
3. Test functionality
```

## Step 1: Create Web Search Tool Instance

### Get Project ID


```bash
# List projects with IDs
tdx llm project list --format json 2>&1 | tail -n +2 | jq -r '.[] | {id, name}'

# Or store in variable
PROJECT_ID="<your-project-id>"
```

### Create Web Search Tool


```bash
cat > web_search_tool.json <<EOF
{
  "data": {
    "type": "webSearchTools",
    "attributes": {
      "name": "my_web_search_tool",
      "projectId": "$PROJECT_ID",
      "modelType": "gpt-5-mini",
      "systemPrompt": "You are a focused web search assistant. Answer only with the information requested.",
      "searchContextSize": "medium",
      "filters": {
        "allowed_domains": [
          "example.com",
          "openai.com"
        ]
      }
    }
  }
}
EOF

tdx api -X POST --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f web_search_tool.json \
  /api/web_search_tools
```

**Save the `data.id` from the response** for later direct API calls (for example, `GET`/`PATCH`) and verification. The `agent.yml` example in this guide refers to the tool by name.

## Step 2: Add to agent.yml

### Pull Existing Agent


```bash
# Pull agent configuration
tdx agent pull "Project Name" -y
```

### Edit agent.yml

Add to `agents/Project Name/agent-name/agent.yml`:


```yaml
tools:
  - type: web_search
    target: '@ref(type: "web_search_tool", name: "my_web_search_tool")'
    target_function: SEARCH
    function_name: search_web
    function_description: Search the web for current information
```

**Key points:**

- `target` name must match `attributes.name` from Step 1
- `function_description` guides the LLM's tool selection decisions


### Apply Changes


```bash
tdx agent push "agents/Project Name/" -y
```

## Step 3: Test


```bash
tdx chat --agent "Project Name/agent-name" \
  --new "What is the latest news about Anthropic?"
```

Success if web search executes and returns current information.

## Configuration Reference

### Web Search Tool Settings

| Parameter | Required | Default | Description |
|  --- | --- | --- | --- |
| `name` | ✅ | - | Tool name (referenced in @ref) |
| `projectId` | ✅ | - | Project ID |
| `modelType` | ✅ | - | `gpt-5-mini` |
| `systemPrompt` | ❌ | null | System prompt for web search |
| `searchContextSize` | ❌ | `medium` | `low` / `medium` / `high` |
| `userLocation` | ❌ | null | Location object for regional optimization |
| `filters.allowed_domains` | Conditional | `[]` | Allowed domain list (max 20, no `https://`). If you include `filters`, you must include `allowed_domains`; an empty array (`[]`) is allowed. |


### userLocation Example


```json
"userLocation": {
  "type": "approximate",
  "country": "JP",
  "city": "Minato",
  "region": "Tokyo",
  "timezone": "Asia/Tokyo"
}
```

### agent.yml Tools Configuration

| Field | Required | Description |
|  --- | --- | --- |
| `type` | ✅ | `web_search` (fixed) |
| `target` | ✅ | `@ref(type: "web_search_tool", name: "...")` |
| `target_function` | ✅ | `SEARCH` (fixed) |
| `function_name` | ✅ | Function name shown to LLM |
| `function_description` | ✅ | Function description shown to LLM |


## Cost Optimization

**To reduce costs:**

1. **modelType**: Use `gpt-5-mini`
2. **searchContextSize**: Use `low` or `medium` (`high` is expensive)
3. **allowed_domains**: Restrict to trusted domains only
4. **systemPrompt**: Include instructions for concise responses


**Update example:**


```bash
cat > update.json <<EOF
{
  "data": {
    "type": "webSearchTools",
    "attributes": {
      "modelType": "gpt-5-mini",
      "searchContextSize": "low"
    }
  }
}
EOF

tdx api -X PATCH --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f update.json \
  /api/web_search_tools/<TOOL_ID>
```

## Troubleshooting

### Web search not executing

**Cause:**

- Web Search Tool feature not enabled for account
- Web Search Tool instance doesn't exist


**Solution:**


```bash
# Verify Web Search Tool exists
tdx api --type llm /api/web_search_tools | jq '.data[] | {id, name, projectId}'

# Contact Support for feature enablement
```

### allowed_domains settings not applied

**Cause:**

- Including `https://` in domain names
- Adding subdomains individually


**Solution:**

- Specify domain only: `openai.com` (not `https://openai.com`)
- Subdomains are automatically allowed (no need to add separately)


### Higher costs than expected

**Cause:**

- Using `searchContextSize: high`


**Solution:**

- See "Cost Optimization" section above


### Content-Type error (HTTP 415)

**Cause:**

- Missing `Content-Type: application/vnd.api+json` header in API call


**Solution:**


```bash
# Required: include the Content-Type header
tdx api -X POST --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f payload.json \
  /api/web_search_tools
```

## API Reference

### Web Search Tool Operations

**List all:**


```bash
tdx api --type llm /api/web_search_tools
```

**Get details:**


```bash
tdx api --type llm /api/web_search_tools/<TOOL_ID>
```

**Update:**


```bash
tdx api -X PATCH --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f update.json \
  /api/web_search_tools/<TOOL_ID>
```

**Delete:**


```bash
tdx api -X DELETE --type llm /api/web_search_tools/<TOOL_ID>
```

### Verify Agent Tools


```bash
# Check tools attached to agent
tdx api --type llm /api/agents/<AGENT_ID> | jq '.data.attributes.tools'
```

**Expected output:**


```json
[
  {
    "toolTargetId": "<WEB_SEARCH_TOOL_ID>",
    "targetFunction": "SEARCH",
    "functionName": "search_web",
    "functionDescription": "Search the web for current information",
    "toolTargetType": "WebSearchTool"
  }
]
```

## FAQ

**Q: How to add to new project/agent?**

A: After creating project, create Web Search Tool with new project ID in Step 1. For agent creation, use API with explicit `projectId`:


```bash
cat > agent.json <<EOF
{
  "data": {
    "type": "agents",
    "attributes": {
      "name": "new-agent",
      "projectId": "$PROJECT_ID",
      "systemPrompt": "Your prompt here",
      "modelType": "claude-4.5-sonnet"
    }
  }
}
EOF

tdx api -X POST --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f agent.json \
  /api/agents
```

**Q: Correct Claude model name format?**

A: `claude-4.5-sonnet` (note hyphens and periods)

**Q: Using multiple tools together?**

A: Add multiple tool definitions under `tools:` in agent.yml:


```yaml
tools:
  - type: knowledge_base
    target: '@ref(type: "knowledge_base", name: "product-catalog")'
    target_function: SEARCH
    function_name: search_products
    function_description: Search internal product catalog

  - type: web_search
    target: '@ref(type: "web_search_tool", name: "my_web_search_tool")'
    target_function: SEARCH
    function_name: search_web
    function_description: Search the web for current information
```

**Document Version:** v2.1
**Last Updated:** 2026-03-16