> ## 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`。

`web_search` 让智能体进行全网搜索。默认通过火山引擎融合信息搜索 API 搜索，详见[融合信息搜索 API 文档](https://www.volcengine.com/docs/85508/1650263)。当 `CLOUD_PROVIDER` 设为 `byteplus` 时，工具改用 BytePlus SearchInfinity API 搜索。

导入路径：`from veadk.tools.builtin_tools.web_search import web_search`

`parallel_web_search` 提供并行搜索能力，同样在 BytePlus 模式下使用 BytePlus SearchInfinity API。

## 环境变量与前提

<Warning>
  附加要求：

  1. 配置火山引擎 AK / SK，或使用火山引擎 IAM 授权的临时 StsToken；BytePlus 模式下改为使用 `BYTEPLUS_WEB_SEARCH_API_KEY`。
  2. 配置用于智能体推理模型的 API Key。
</Warning>

| 环境变量 | 适用模式 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `MODEL_AGENT_API_KEY` | 通用 | — | 智能体推理模型的 API Key。 |
| `CLOUD_PROVIDER` | 通用 | `volcengine` | 云服务商，设为 `byteplus` 时切换到 BytePlus 搜索。 |
| `VOLCENGINE_ACCESS_KEY` | 火山引擎 | — | 火山引擎 AccessKey。 |
| `VOLCENGINE_SECRET_KEY` | 火山引擎 | — | 火山引擎 SecretKey。 |
| `BYTEPLUS_WEB_SEARCH_API_KEY` | BytePlus | — | BytePlus SearchInfinity API 的 API Key，BytePlus 模式下必填。 |
| `BYTEPLUS_WEB_SEARCH_URL` | BytePlus | `https://torchlight.byteintlapi.com/search_api/web_search` | 覆盖 BytePlus SearchInfinity 搜索端点。 |

或在 `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:
  # 供 Viking DB 与 web_search 等工具使用
  access_key: your-access-key-here
  secret_key: your-secret-key-here
```

BytePlus 模式示例：

```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"
```

## 使用方法

```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("杭州今天的天气怎么样？")
    print(response)


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

## 参数与返回值

| 工具 | 参数 | 类型 | 默认值 | 返回值 |
| :- | :- | :- | :- | :- |
| `web_search` | `query` | `str` | 必填 | 单次查询的摘要列表 |
| `parallel_web_search` | `queries` | `list[str]` | 必填 | 查询字符串到摘要列表的映射 |
| 两者 | `tool_context` | `ToolContext \| None` | `None` | 智能体调用时自动注入，可提供火山引擎凭证 |

火山引擎模式下，凭证优先级为：成对设置的 `TOOL_WEB_SEARCH_ACCESS_KEY` / `TOOL_WEB_SEARCH_SECRET_KEY`、当前工具上下文中的 AK/SK、`VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY`、托管运行环境提供的 IAM 临时凭证。临时令牌来自最后一种 IAM 凭证方式，直接设置 AK/SK 不会自动附加任意 STS 令牌

每个查询最多请求 5 条结果。并行结果以查询文本作为字典键，重复查询会合并到同一个键；调用前应去重。错误响应可能作为列表元素返回，应检查内容后再用于回答

以下示例只调用搜索服务，不调用推理模型：

```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())
```