# 工具概述

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

在生成模型响应时，您可以使用方舟大模型内置工具、函数调用（Function Calling）以及 MCP 等工具来扩展模型的功能。
这些功能使模型能够自行判断，并决策是否调用搜索网络资料、图片处理等内置工具或者您自己的自定义函数。

<span id="quickstart"></span>
## 快速入门

> **说明**
>
> 请将示例代码中的占位符替换为真实值。关于 `<ARK_API_KEY>` 的获取方法，请参见[快速入门](/docs/quick-start)。关于 `<knowledge_resource_id>` 的获取方法，请参见 [查看知识库详情](https://docs.volcengine.com/docs/vector_database_vikingdb/Viewingknowledgebasedetails?lang=zh)。

**选项：豆包助手 API**

```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--header 'ark-beta-doubao-app: true' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "tools": [
        {
            "type": "doubao_app",
            "feature": {
                "ai_search": {
                    "type": "enabled",
                    "role_description": "你是科技领域助手，专业解答行业问题"
                }
            }
        }
    ],
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "今天有什么AI领域热点新闻"
                }
            ]
        }
    ]
}'
```

**选项：联网内容插件**

```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer <ARK_API_KEY>" \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "tools": [
        {"type": "web_search"}
    ],
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "今天有什么热点新闻"
                }
            ]
        }
    ]
}'
```

**选项：豆包搜索 Custom 版**

```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "tools": [
        {
            "type": "web_search",
            "sources": ["doubao"]
        }
    ],
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "今天有什么 AI 领域的热点新闻？"
                }
            ]
        }
    ]
}'
```

**选项：图像处理**

```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ARK_API_KEY>' \
--header 'ark-beta-image-process: true' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "tools": [
        {"type": "image_process"}
    ],
    "input": [
        {
            "type": "message",
            "role": "system",
            "content": [
                {
                    "type": "input_text",
                    "text": "数一数有多少颗草莓？"
                },
                {
                    "type": "input_image",
                    "image_url": "https://arkdocs.tos-cn-beijing.volces.com/images/tool-calling/image_process_2.jpg"
                }
            ]
        }
    ]
}'
```

**选项：私域知识库搜索**

```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ARK_API_KEY>' \
--header 'ark-beta-knowledge-search: true' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "thinking": {
        "type": "disabled"
    },
    "tools": [
        {
            "type": "knowledge_search",
            "knowledge_resource_id": "<knowledge_resource_id>",
            "limit": 2,
            "ranking_options": {
                "get_attachment_link": true
            }
        }
    ],
    "input": [
        {
            "role": "user",
            "content": "机票选择页面中，如何选择该航班不同价格的机票？"
        }
    ],
    "max_tool_calls": 1
}'
```

**选项：MCP**

```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer <ARK_API_KEY>" \
--header 'Content-Type: application/json' \
--header 'ark-beta-mcp: true' \
--data '{
    "model": "doubao-seed-2-1-pro-260915",
    "stream": true,
    "tools": [
        {
            "type": "mcp",
            "server_label": "deepwiki",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "require_approval": "never"
        }
    ],
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "看一下volcengine/ai-app-lab这个repo的文档"
                }
            ]
        }
    ]
}'
```

**选项：函数调用**

```Python
from arkruntime import Ark
from arkruntime.types.chat import ChatCompletion
import json
client = Ark(
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)
messages = [
    {"role": "user", "content": "北京和上海今天的天气如何？"}
]
# 步骤1: 定义工具
tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "获取指定地点的天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "地点的位置信息，例如北京、上海"
                },
                "unit": {
                    "type": "string",
                    "enum": ["摄氏度", "华氏度"],
                    "description": "温度单位"
                }
            },
            "required": ["location"]
        }
    }
}]
def get_current_weather(location: str, unit="摄氏度"):
    # 实际调用天气查询 API 的逻辑
    # 此处为示例，返回模拟的天气数据
    return f"{location}今天天气晴朗，温度 25 {unit}。"
while True:
    # 步骤2: 发起模型请求，由于模型在收到工具执行结果后仍然可能有工具调用意愿，因此需要多次请求
    completion: ChatCompletion = client.chat.completions.create(
        model="doubao-seed-2-1-pro-260915",
        messages=messages,
        tools=tools
    )
    resp_msg = completion.choices[0].message
    # 展示模型中间过程的回复内容
    print(resp_msg.content)
    if completion.choices[0].finish_reason != "tool_calls":
        # 模型最终总结，没有调用工具意愿
        break
    messages.append(completion.choices[0].message.model_dump())
    tool_calls = completion.choices[0].message.tool_calls
    for tool_call in tool_calls:
        tool_name = tool_call.function.name
        if tool_name == "get_current_weather":
            # 步骤 3：调用外部工具
            args = json.loads(tool_call.function.arguments)
            tool_result = get_current_weather(**args)
            # 步骤 4：回填工具结果，并获取模型总结回复
            messages.append(
                {"role": "tool", "content": tool_result, "tool_call_id": tool_call.id}
            )
```

<span id="available-tools"></span>
## 支持的工具

<span id="built-in-tools"></span>
### 内置工具

当通过 Responses API 创建模型响应时，您可以通过在参数中配置 `tools` 字段来访问工具。每个工具中都有独特的配置要求，具体见如下教程：

* [豆包助手 API](/docs/doubao-assistant)

    为您的应用快速集成与豆包 App 同款的 AI 功能，例如日常沟通、深度沟通和联网搜索，快速获得安全、可靠且可控的优质 AI 体验。

* [联网搜索工具](/docs/web-search)

    支持豆包搜索 Custom 版和联网内容插件两种工具，可获取实时公开网络信息（如新闻、商品、天气等），解决数据时效性、知识盲区、信息同步等核心问题，并且无需自行开发搜索引擎或维护数据资源。

* [Image Process（图像处理工具）](/docs/image-process)

    支持通过 Responses API 调用对输入图片执行画点、画线、旋转、缩放、框选/裁剪关键区域等基础操作，适用于需模型通过视觉处理提升图片理解的场景（如图文内容分析、物体定位标注、多轮视觉推理等）。工具通过模型自动判断图像处理逻辑，支持与自定义函数混合使用，且可处理多轮视觉输入（上一轮输出图片作为下一轮输入）。

* [Knowledge Search（私域知识库搜索工具）](/docs/knowledge-search)

    支持通过 Responses API 调用直接获取企业私域知识库中的信息（如内部文档、产品手册、行业资料等），适用于需基于企业专属数据解答问题的场景（如内部培训问答、产品功能咨询、行业方案查询等）。工具通过模型自动判断是否需要调用私域知识库，支持与自定义函数、MCP 等工具混合使用，目前仅支持旗舰版知识库。

* [Apply Patch（代码补丁工具）](/docs/apply-patch)

    支持通过结构化补丁格式创建、更新或删除文件，适用于让模型直接生成文件修改方案的场景（如批量代码改写、机械化重构、测试文件生成等）。通过 Responses API 既可以将其作为内置工具直接启用，也可以按自定义工具方式接入，以兼容现有工具编排流程。

<span id="custom-function"></span>
### 自定义函数

您也可以在创建模型响应时，使用 `tools` 来定义自定义函数。模型通过调用自定义函数代码，来访问模型中无法直接使用的特定数据或功能。了解更多信息，请参见[Function Calling（函数调用）](/docs/function-calling)。

<span id="mcp"></span>
### 云部署 MCP 或 Remote MCP

Responses API 支持通过 Streamable HTTP 链接的 MCP 调用。适用于复杂任务（如多步数据查询 + 分析）场景，支持与自定义函数、Web Search 工具混合使用。详情请参见[云部署 MCP / Remote MCP](/docs/mcp-remote-mcp)。