火山方舟
火山方舟
文档指南
请输入
调用
视频生成
工具调用
使用 Responses API
推理
训练
模型精调
Managed Agents
配置 Agent 环境
委派任务给 Agent
管理 Agent 上下文
高级能力
- 文档首页
火山方舟调用使用 Responses API工具调用
复制全文
下载 pdf工具调用
文档反馈
问问助手Responses API 支持使用方舟大模型内置工具、函数调用 Function Calling 等工具来扩展模型的功能。这些功能使模型能够搜索网络资料、图片处理、私域知识库搜索或者调用自定义函数。
快速开始
以天气查询场景为例，介绍使用函数调用 Function Calling 的方法。
Curl
Python
Go
Java
OpenAI SDK
第一轮请求： 触发工具调用
curl https://ark.cn-beijing.volces.com/api/v3/responses \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-2-1-pro-260915",
"store": true,
"input": [
{
"type": "message",
"role": "user",
"content": "查询北京今天的天气"
}
],
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "根据城市名称查询该城市当日天气（含温度、天气状况）",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称，如北京、上海（仅支持国内地级市）"
}
},
"required": ["location"]
}
}
]
}'
第一轮响应：返回 function_call 指令
模型会返回工具调用指令，关键字段为call_id（关联后续结果）、arguments（调用参数）：
{
"created_at": 1756980000,
"id": "resp_02175698000123456789abcdef0123",
"model": "doubao-seed-2-1-pro-260915",
"object": "response",
"output": [
{
"arguments": "{\"location\":\"北京\"}",
"call_id": "call_abc123def456ghi789jkl0",
"name": "get_weather",
"type": "function_call",
"id": "fc_02175698000abcdef0123456789gh",
"status": "completed"
}
],
"status": "completed",
"store": true,
"expire_at": 1757239200
}
执行工具：获取天气结果
开发者根据 arguments 调用实际天气工具（如第三方天气 API），假设返回结果为：
{
"city": "北京",
"date": "2025-10-13",
"temperature": "18~28℃",
"condition": "晴转多云",
"wind": "东北风2级"
}
第二轮请求：回传结果并生成最终响应
传入上一轮 response_id、工具结果，模型生成自然语言回答：
curl https://ark.cn-beijing.volces.com/api/v3/responses \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-2-1-pro-260915",
"previous_response_id": "resp_02175698000123456789abcdef0123",
"input": [
{
"type": "function_call_output",
"call_id": "call_abc123def456ghi789jkl0",
"output": "{\"city\":\"北京\",\"date\":\"2025-10-13\",\"temperature\":\"18~28℃\",\"condition\":\"晴转多云\",\"wind\":\"东北风2级\"}"
}
]
}'
第二轮响应：生成最终回答
模型结合工具结果，返回自然语言响应：
{
"created_at": 1756980100,
"id": "resp_02175698010abcdef0123456789gh",
"model": "doubao-seed-2-1-pro-260915",
"object": "response",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "北京今天（2025-10-13）的天气为晴转多云，气温在18~28℃之间，东北风2级。"
}
],
"status": "completed",
"id": "msg_02175698010abcdef0123456789ij"
}
],
"status": "completed",
"store": true
}
import os
from arkruntime import Ark
import json
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
# Define the tool (weather query tool)
weather_tool = [
{
"type": "function",
"name": "get_weather",
"description": "根据城市名称查询该城市当日天气（含温度、天气状况）",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称，如北京、上海（仅支持国内地级市）"
}
},
"required": ["location"]
}
}
]
# ------------------- First Round Request: Trigger Tool Call -------------------
print("=== First Round Request: Trigger Tool Call ===")
first_response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
store=True,
input=[
{
"type": "message",
"role": "user",
"content": "查询北京今天的天气"
}
],
tools=weather_tool
)
# Extract key information（previous_response_id、call_id、arguments）
previous_response_id = first_response.id
function_call = next(
item for item in first_response.output if item.type == "function_call"
)
call_id = function_call.call_id
call_arguments = function_call.arguments
print(f"First Round Response ID：{previous_response_id}")
print(f"Tool Call ID：{call_id}")
print(f"Call Parameters：{call_arguments}")
# ------------------- Simulate Tool Execution: Get Weather Results -------------------
print("=== Simulate Tool Execution: Get Weather Results ===")
# In real scenarios, call a third-party weather API here; we use mock data instead.
tool_output = {
"city": "北京",
"date": "2025-10-13",
"temperature": "18~28℃",
"condition": "晴转多云",
"wind": "东北风2级"
}
print(f"Tool Return Result：{tool_output}")
# ------------------- Second Round Request: Return Result and Generate Final Response -------------------
print("=== Second Round Request: Return Result and Generate Final Response ===")
second_response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
previous_response_id=previous_response_id,
input=[
{
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(tool_output, ensure_ascii=False)
}
]
)
# Extract and print the final answer
final_answer = next(
item for item in second_response.output if item.type == "message"
)
print("=== Final Answer ===")
print(final_answer.content[0].text)
package main
import (
"context"
"encoding/json"
"fmt"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
tool := weatherTool()
response, err := client.CreateResponses(context.Background(), &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260915",
Input: responses.NewStringResponsesInput("北京的天气怎么样？"),
Store: responses.NewOptBool(true),
Tools: []responses.Tool{tool},
})
if err != nil {
fmt.Printf("response error: %v\n", err)
return
}
call, ok := functionCall(response.Output)
if !ok {
fmt.Println(response)
return
}
fmt.Printf(
"response_id=%s call_id=%s arguments=%s\n",
response.ID,
call.CallID.Or(""),
call.Arguments.Or(""),
)
toolOutput, err := json.Marshal(map[string]string{
"city": "北京", "condition": "晴转多云", "temperature": "18-28 C",
})
if err != nil {
panic(err)
}
second, err := client.CreateResponses(context.Background(), &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260915",
PreviousResponseID: responses.NewOptString(response.ID),
Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{
{
OneOf: responses.NewItemFunctionToolCallOutputInputItemSum(
responses.ItemFunctionToolCallOutput{
Type: responses.ItemFunctionToolCallOutputTypeFunctionCallOutput,
CallID: responses.NewOptString(call.CallID.Or("")),
Output: responses.NewOptMessageContent(
responses.NewStringMessageContent(string(toolOutput)),
),
},
),
},
}),
})
if err != nil {
fmt.Printf("response error: %v\n", err)
return
}
fmt.Println(second)
}
func weatherTool() responses.Tool {
var parameters responses.FunctionToolParameters
schema := `{"type":"object","properties":{"location":{"type":"string","description":"城市名称，如北京、上海"}},"required":["location"]}`
if err := json.Unmarshal([]byte(schema), ¶meters); err != nil {
panic(err)
}
return responses.Tool{
OneOf: responses.NewFunctionToolToolSum(responses.FunctionTool{
Name: "get_weather",
Type: responses.FunctionToolTypeFunction,
Description: responses.NewOptString("根据城市名称查询该城市当日天气"),
Parameters: responses.NewOptFunctionToolParameters(parameters),
}),
}
}
func functionCall(items []responses.OutputItem) (responses.ItemFunctionToolCall, bool) {
for _, item := range items {
if call, ok := item.OneOf.GetItemFunctionToolCall(); ok {
return call, true
}
}
return responses.ItemFunctionToolCall{}, false
}
package com.ark.example;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.volcengine.ark.runtime.models.responses.*;
import com.volcengine.ark.runtime.service.ArkService;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.*;
public class demo {
public static ObjectMapper om = new ObjectMapper();
public static List<Tool> buildTools() {
JsonNode params = om.createObjectNode()
.put("type", "object")
.set("properties", om.createObjectNode()
.set("location", om.createObjectNode()
.put("type", "string")
.put("description", "城市名称，如北京、上海（仅支持国内地级市）")));
FunctionTool t = FunctionTool.builder()
.name("get_weather")
.description("根据城市名称查询该城市当日天气（含温度、天气状况）")
.parameters(om.convertValue(params, Map.class))
.build();
return Arrays.asList(t);
}
public static void main(String[] args) throws JsonProcessingException {
String apiKey = System.getenv("ARK_API_KEY");
ArkService arkService = ArkService.builder().apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
System.out.println("=== First Round Request: Trigger Tool Call ===");
ResponsesRequest req = ResponsesRequest.builder()
.model("doubao-seed-2-1-pro-260915")
.store(true)
.input(ResponsesInput.ofList(java.util.Arrays.asList(ItemEasyMessage.builder().role(MessageRole.USER).content(
MessageContent.ofList(java.util.Arrays.asList(ContentItemText.builder().text("查询北京今天的天气").build()))
).build())))
.tools(buildTools())
.build();
Response resp = arkService.createResponse(req);
System.out.println(resp);
// Extract key information（previous_response_id、call_id、arguments）
String previousId = resp.getId();
OutputItem targetCall = null;
for(OutputItem item : resp.getOutput()) {
if (item.getType() == ItemType.FUNCTION_CALL) {
targetCall = item;
break;
}
}
ObjectMapper objectMapper = new ObjectMapper();
String jsonStr = objectMapper.writeValueAsString(targetCall);
ItemFunctionToolCall functionCall = objectMapper.readValue(jsonStr, ItemFunctionToolCall.class);
String callId = functionCall.getCallId();
String callArguments = functionCall.getArguments();
System.out.println("First Round Response ID:" + previousId);
System.out.println("Tool Call ID:" + callId);
System.out.println("Call Parameters:" + callArguments);
System.out.println("=== Simulate Tool Execution: Get Weather Results ===");
Map<String, String> toolOutput = new HashMap<String, String>() {{
put("city", "北京");
put("date", "2025-10-13");
put("temperature", "18~28℃");
put("condition", "晴转多云");
put("wind", "东北风2级");
}};
System.out.println(toolOutput);
System.out.println("=== Second Round Request: Return Result and Generate Final Response ===");
ResponsesRequest secondReq = ResponsesRequest.builder()
.model("doubao-seed-2-1-pro-260915")
.previousResponseId(previousId)
.input(ResponsesInput.ofList(java.util.Arrays.asList(ItemFunctionToolCallOutput.builder().callId(callId).output(MessageContent.ofString(objectMapper.writeValueAsString(toolOutput))).build())))
.tools(buildTools())
.build();
Response secondResp = arkService.createResponse(secondReq);
System.out.println("=== Final Answer ===");
System.out.println(secondResp);
arkService.shutdownExecutor();
}
}
import os
from openai import OpenAI
import json
# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key = os.getenv('ARK_API_KEY')
client = OpenAI(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
# Define the tool (weather query tool)
weather_tool = [
{
"type": "function",
"name": "get_weather",
"description": "根据城市名称查询该城市当日天气（含温度、天气状况）",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称，如北京、上海（仅支持国内地级市）"
}
},
"required": ["location"]
}
}
]
# ------------------- First Round Request: Trigger Tool Call -------------------
print("=== First Round Request: Trigger Tool Call ===")
first_response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
store=True,
input=[
{
"type": "message",
"role": "user",
"content": "查询北京今天的天气"
}
],
tools=weather_tool
)
# Extract key information（previous_response_id、call_id、arguments）
previous_response_id = first_response.id
function_call = next(
item for item in first_response.output if item.type == "function_call"
)
call_id = function_call.call_id
call_arguments = function_call.arguments
print(f"First Round Response ID：{previous_response_id}")
print(f"Tool Call ID：{call_id}")
print(f"Call Parameters：{call_arguments}")
# ------------------- Simulate Tool Execution: Get Weather Results -------------------
print("=== Simulate Tool Execution: Get Weather Results ===")
tool_output = {
"city": "北京",
"date": "2025-10-13",
"temperature": "18~28℃",
"condition": "晴转多云",
"wind": "东北风2级"
}
print(f"Tool Return Result：{tool_output}")
# ------------------- Second Round Request: Return Result and Generate Final Response-------------------
print("=== Second Round Request: Return Result and Generate Final Response ===")
second_response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
previous_response_id=previous_response_id,
input=[
{
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(tool_output, ensure_ascii=False)
}
]
)
# Extract and print the final answer
final_answer = next(
item for item in second_response.output if item.type == "message"
)
print("=== Final Answer ===")
print(final_answer.content[0].text)
支持的工具
内置工具
当通过 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。
最近更新时间：2026.10.09 14:36:34
这个页面对您有帮助吗？
有用
有用
无用
无用