在生成模型响应时，您可以使用方舟大模型内置工具、函数调用（Function Calling）以及 MCP 等工具来扩展模型的功能。
这些功能使模型能够自行判断，并决策是否调用搜索网络资料、图片处理等内置工具或者您自己的自定义函数。
快速入门#
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领域热点新闻"
}
]
}
]
}'
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": "今天有什么热点新闻"
}
]
}
]
}'
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 领域的热点新闻？"
}
]
}
]
}'
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"
}
]
}
]
}'
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
}'
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的文档"
}
]
}
]
}'
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}
)
支持的工具#
内置工具#
当通过 Responses API 创建模型响应时，您可以通过在参数中配置 tools 字段来访问工具。每个工具中都有独特的配置要求，具体见如下教程：
-
为您的应用快速集成与豆包 App 同款的 AI 功能，例如日常沟通、深度沟通和联网搜索，快速获得安全、可靠且可控的优质 AI 体验。
-
支持豆包搜索 Custom 版和联网内容插件两种工具，可获取实时公开网络信息（如新闻、商品、天气等），解决数据时效性、知识盲区、信息同步等核心问题，并且无需自行开发搜索引擎或维护数据资源。
-
支持通过 Responses API 调用对输入图片执行画点、画线、旋转、缩放、框选/裁剪关键区域等基础操作，适用于需模型通过视觉处理提升图片理解的场景（如图文内容分析、物体定位标注、多轮视觉推理等）。工具通过模型自动判断图像处理逻辑，支持与自定义函数混合使用，且可处理多轮视觉输入（上一轮输出图片作为下一轮输入）。
-
支持通过 Responses API 调用直接获取企业私域知识库中的信息（如内部文档、产品手册、行业资料等），适用于需基于企业专属数据解答问题的场景（如内部培训问答、产品功能咨询、行业方案查询等）。工具通过模型自动判断是否需要调用私域知识库，支持与自定义函数、MCP 等工具混合使用，目前仅支持旗舰版知识库。
-
支持通过结构化补丁格式创建、更新或删除文件，适用于让模型直接生成文件修改方案的场景（如批量代码改写、机械化重构、测试文件生成等）。通过 Responses API 既可以将其作为内置工具直接启用，也可以按自定义工具方式接入，以兼容现有工具编排流程。
自定义函数#
您也可以在创建模型响应时，使用 tools 来定义自定义函数。模型通过调用自定义函数代码，来访问模型中无法直接使用的特定数据或功能。了解更多信息，请参见Function Calling（函数调用）。
云部署 MCP 或 Remote MCP#
Responses API 支持通过 Streamable HTTP 链接的 MCP 调用。适用于复杂任务（如多步数据查询 + 分析）场景，支持与自定义函数、Web Search 工具混合使用。详情请参见云部署 MCP / Remote MCP。