> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Web search

## Overview

Tool identifier `web_search`.

`web_search` lets the agent run web-wide searches. By default it uses the Volcengine Unified Information Search API; see the [API docs](https://www.volcengine.com/docs/85508/1650263). When `CLOUD_PROVIDER` is set to `byteplus`, the tool switches to the BytePlus SearchInfinity API.

Import path: `from veadk.tools.builtin_tools.web_search import web_search`

`parallel_web_search` provides parallel multi-query search and likewise uses the BytePlus SearchInfinity API in BytePlus mode.

## Environment & prerequisites

<Warning>
  Requirements:

  1. Configure Volcengine AK / SK, or use a temporary StsToken issued via Volcengine IAM. In BytePlus mode, use `BYTEPLUS_WEB_SEARCH_API_KEY` instead.
  2. Configure the API key for the agent's reasoning model.
</Warning>

| Environment variable | Mode | Default | Description |
| :- | :- | :- | :- |
| `MODEL_AGENT_API_KEY` | All | — | API key for the agent's reasoning model. |
| `CLOUD_PROVIDER` | All | `volcengine` | Cloud provider; set to `byteplus` to switch to BytePlus search. |
| `VOLCENGINE_ACCESS_KEY` | Volcengine | — | Volcengine AccessKey. |
| `VOLCENGINE_SECRET_KEY` | Volcengine | — | Volcengine SecretKey. |
| `BYTEPLUS_WEB_SEARCH_API_KEY` | BytePlus | — | API key for the BytePlus SearchInfinity API; required in BytePlus mode. |
| `BYTEPLUS_WEB_SEARCH_URL` | BytePlus | `https://torchlight.byteintlapi.com/search_api/web_search` | Override the BytePlus SearchInfinity search endpoint. |

Or configure in `config.yaml`:

```yaml title="config.yaml" lines theme={null}
model:
  agent:
    provider: openai
    name: doubao-seed-2-1-pro-260628
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
volcengine:
  # used by Viking DB, web_search, and other tools
  access_key: your-access-key-here
  secret_key: your-secret-key-here
```

BytePlus mode example:

```bash lines theme={null}
export CLOUD_PROVIDER="byteplus"
export BYTEPLUS_WEB_SEARCH_API_KEY="your-byteplus-search-api-key"
export MODEL_AGENT_API_KEY="your-model-api-key"
```

## Usage

```python title="examples/tools/web_search/agent.py" lines theme={null}
import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.web_search import web_search

agent = Agent(
    name="web_search_agent",
    model_name="doubao-seed-2-1-pro-260628",
    description="An agent that answers questions with web search.",
    instruction="You are a helpful assistant. Use the web_search tool when you need fresh information.",
    tools=[web_search],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("What's the weather in Hangzhou today?")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())
```

## Parameters and results

| Tool | Parameter | Type | Default | Result |
| :- | :- | :- | :- | :- |
| `web_search` | `query` | `str` | Required | Summary list for one query |
| `parallel_web_search` | `queries` | `list[str]` | Required | Mapping from query strings to summary lists |
| Both | `tool_context` | `ToolContext \| None` | `None` | Injected during agent calls; may supply Volcengine credentials |

In Volcengine mode, credentials are resolved in this order: paired `TOOL_WEB_SEARCH_ACCESS_KEY` / `TOOL_WEB_SEARCH_SECRET_KEY`, AK/SK in the tool context, `VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY`, and IAM temporary credentials from a managed environment. The session token comes from that final IAM flow; setting AK/SK directly does not attach an arbitrary STS token.

Each query requests up to five results. Parallel results use query text as dictionary keys, so deduplicate queries first. An error response may appear as a list item; inspect results before using them in an answer.

This example calls the search service without a reasoning model:

```python lines theme={null}
import asyncio
from veadk.tools.builtin_tools.parallel_web_search import parallel_web_search

async def main():
    results = await parallel_web_search(["AgentKit documentation", "VeADK documentation"])
    for query, summaries in results.items():
        print(query, summaries)

asyncio.run(main())
```