OpenAI 使用工具
生成响应或构建智能体时,可以通过内置工具、函数调用、程序化工具调用、工具搜索和远程MCP服务器扩展能力:搜索网页、检索文件、在运行时加载延迟工具定义、调用自有函数、用JavaScript组合工具调用,或访问第三方服务。只有 gpt-5.4 及后续模型支持 tool_search。
按运行环境选择集成方式:在Responses请求、Agents API智能体或Agents SDK定义中配置工具。可用工具、配置和调用处理方式因集成而异。下面的主要示例采用Responses API。
网页搜索
为模型响应引入网页搜索结果。
来源示例1(javascript)
程序中的自然语言译释22:
今天有哪些积极的新闻?
// [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6-astra",
tools: [{ type: "web_search" }],
input: "What was a positive news story from today?",
});
console.log(response.output_text);
来源示例2(python)
本段复用的中文释义:译释22。
## [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
tools=[{"type": "web_search"}],
input="What was a positive news story from today?",
)
print(response.output_text)
来源示例3(go)
本段复用的中文释义:译释22。
// [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Tools: []responses.ToolUnionParam{
responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch),
},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What was a positive news story from today?")},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
}
来源示例4(java)
本段复用的中文释义:译释22。
// [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.WebSearchTool;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("What was a positive news story from today?")
.addTool(WebSearchTool.builder().type(WebSearchTool.Type.WEB_SEARCH).build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
来源示例5(csharp)
本段复用的中文释义:译释22。
// [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(ResponseTool.CreateWebSearchTool());
options.InputItems.Add(
ResponseItem.CreateUserMessageItem("What was a positive news story from today?")
);
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());
来源示例6(ruby)
本段复用的中文释义:译释22。
## [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
require "openai"
openai = OpenAI::Client.new
response = openai.responses.create(
model: "gpt-6-astra",
tools: [{ type: "web_search" }],
input: "What was a positive news story from today?"
)
puts(response.output_text)
来源示例7(bash)
本段复用的中文释义:译释22。
## [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [{"type": "web_search"}],
"input": "what was a positive news story from today?"
}'
来源示例8(bash)
本段复用的中文释义:译释22。
## [中文] 在Responses请求中启用网页搜索,输入问题,读取该语言示例实际返回的响应。
openai responses create \
--model gpt-6-astra \
--raw-output \
--transform 'output.#(type=="message").content.0.text' <<'YAML'
tools:
- type: web_search
input: What was a positive news story from today?
YAML
文件搜索
在生成响应时搜索自己的文件。
来源示例9(javascript)
程序中的自然语言译释23:
OpenAI的深度研究是什么?
// [中文] 配置向量库ID供file_search检索;示例ID须替换成自己的资源。
import OpenAI from "openai";
const openai = new OpenAI();
const response = await openai.responses.create({
model: "gpt-6-astra",
input: "What is deep research by OpenAI?",
tools: [
{
type: "file_search",
vector_store_ids: ["<vector_store_id>"],
},
],
});
console.log(response);
来源示例10(python)
本段复用的中文释义:译释23。
## [中文] 配置向量库ID供file_search检索;示例ID须替换成自己的资源。
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
input="What is deep research by OpenAI?",
tools=[{"type": "file_search", "vector_store_ids": ["<vector_store_id>"]}],
)
print(response)
来源示例11(go)
本段复用的中文释义:译释23。
// [中文] 配置向量库ID供file_search检索;示例ID须替换成自己的资源。
package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is deep research by OpenAI?")},
Tools: []responses.ToolUnionParam{responses.ToolParamOfFileSearch([]string{"<vector_store_id>"})},
})
if err != nil {
panic(err)
}
fmt.Println(response)
}
来源示例12(java)
本段复用的中文释义:译释23。
// [中文] 配置向量库ID供file_search检索;示例ID须替换成自己的资源。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
String vectorStoreId = "<vector_store_id>";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("What is deep research by OpenAI?")
.addFileSearchTool(List.of(vectorStoreId))
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
来源示例13(csharp)
本段复用的中文释义:译释23。
// [中文] 配置向量库ID供file_search检索;示例ID须替换成自己的资源。
using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string vectorStoreId = "<vector_store_id>";
ResponsesClient client = new(key);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
ResponseTool.CreateFileSearchTool([vectorStoreId])
);
options.InputItems.Add(
ResponseItem.CreateUserMessageItem("What is deep research by OpenAI?")
);
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());
来源示例14(ruby)
本段复用的中文释义:译释23。
## [中文] 配置向量库ID供file_search检索;示例ID须替换成自己的资源。
require "openai"
openai = OpenAI::Client.new
response = openai.responses.create(
model: "gpt-6-astra",
input: "What is deep research by OpenAI?",
tools: [
{
type: "file_search",
vector_store_ids: ["<vector_store_id>"]
}
]
)
puts(response)
工具搜索
在运行时加载延迟的工具定义。
来源示例15(javascript)
程序中的自然语言译释24:
用于查找客户与管理订单的CRM工具。
程序中的自然语言译释25:
列出客户CUST-12345尚未关闭的订单。
程序中的自然语言译释26:
按客户ID获取客户资料。
程序中的自然语言译释27:
按客户ID列出尚未关闭的订单。
// [中文] 声明延迟加载的CRM函数并启用tool_search,让模型先发现再使用。
import OpenAI from "openai";
const client = new OpenAI();
const crmNamespace = {
type: "namespace",
name: "crm",
description: "CRM tools for customer lookup and order management.",
tools: [
{
type: "function",
name: "get_customer_profile",
description: "Fetch a customer profile by customer ID.",
parameters: {
type: "object",
properties: {
customer_id: { type: "string" },
},
required: ["customer_id"],
additionalProperties: false,
},
},
{
type: "function",
name: "list_open_orders",
description: "List open orders for a customer ID.",
// [中文] 来源展示标记:高亮开始。
// highlight-start:subtle
defer_loading: true,
// [中文] 来源展示标记:高亮结束。
// highlight-end
parameters: {
type: "object",
properties: {
customer_id: { type: "string" },
},
required: ["customer_id"],
additionalProperties: false,
},
},
],
};
const response = await client.responses.create({
model: "gpt-6-astra",
input: "List open orders for customer CUST-12345.",
// [中文] 来源展示标记:高亮开始。
// highlight-start:subtle
tools: [crmNamespace, { type: "tool_search" }],
// [中文] 来源展示标记:高亮结束。
// highlight-end
parallel_tool_calls: false,
});
console.log(response.output);
来源示例16(python)
本段复用的中文释义:译释24、译释25、译释26、译释27。
## [中文] 声明延迟加载的CRM函数并启用tool_search,让模型先发现再使用。
from openai import OpenAI
client = OpenAI()
crm_namespace = {
"type": "namespace",
"name": "crm",
"description": "CRM tools for customer lookup and order management.",
"tools": [
{
"type": "function",
"name": "get_customer_profile",
"description": "Fetch a customer profile by customer ID.",
"parameters": {
"type": "object",
"properties": {
"customer_id": {"type": "string"},
},
"required": ["customer_id"],
"additionalProperties": False,
},
},
{
"type": "function",
"name": "list_open_orders",
"description": "List open orders for a customer ID.",
# [中文] 来源展示标记:高亮开始。
# highlight-start:subtle
"defer_loading": True,
# [中文] 来源展示标记:高亮结束。
# highlight-end
"parameters": {
"type": "object",
"properties": {
"customer_id": {"type": "string"},
},
"required": ["customer_id"],
"additionalProperties": False,
},
},
],
}
response = client.responses.create(
model="gpt-6-astra",
input="List open orders for customer CUST-12345.",
tools=[
crm_namespace,
# [中文] 来源展示标记:高亮开始。
# highlight-start:subtle
{"type": "tool_search"},
# [中文] 来源展示标记:高亮结束。
# highlight-end
],
parallel_tool_calls=False,
)
print(response.output)
来源示例17(go)
本段复用的中文释义:译释24、译释25、译释26、译释27。
// [中文] 声明延迟加载的CRM函数并启用tool_search,让模型先发现再使用。
package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{"customer_id": map[string]any{"type": "string"}},
"required": []string{"customer_id"},
"additionalProperties": false,
}
namespace := responses.ToolParamOfNamespace(
"CRM tools for customer lookup and order management.",
"crm",
[]responses.NamespaceToolToolUnionParam{
{OfFunction: &responses.NamespaceToolToolFunctionParam{
Name: "get_customer_profile", Description: openai.String("Fetch a customer profile by customer ID."), Parameters: parameters,
}},
{OfFunction: &responses.NamespaceToolToolFunctionParam{
Name: "list_open_orders", Description: openai.String("List open orders for a customer ID."), DeferLoading: openai.Bool(true), Parameters: parameters,
}},
},
)
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("List open orders for customer CUST-12345.")},
Tools: []responses.ToolUnionParam{namespace, {OfToolSearch: &responses.ToolSearchToolParam{}}},
ParallelToolCalls: openai.Bool(false),
})
if err != nil {
panic(err)
}
fmt.Println(response.Output)
}
来源示例18(java)
本段复用的中文释义:译释24、译释25、译释26、译释27。
// [中文] 声明延迟加载的CRM函数并启用tool_search,让模型先发现再使用。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.NamespaceTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ToolSearchTool;
import java.util.List;
import java.util.Map;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("List open orders for customer CUST-12345.")
.parallelToolCalls(false)
.addTool(
NamespaceTool.builder()
.name("crm")
.description("CRM tools for customer lookup and order management.")
.addTool(
NamespaceTool.Tool.Function.builder()
.name("get_customer_profile")
.description("Fetch a customer profile by customer ID.")
.strict(true)
.parameters(
JsonValue.from(
Map.of(
"type",
"object",
"properties",
Map.of("customer_id", Map.of("type", "string")),
"required",
List.of("customer_id"),
"additionalProperties",
false)))
.build())
.addTool(
NamespaceTool.Tool.Function.builder()
.name("list_open_orders")
.description("List open orders for a customer ID.")
.deferLoading(true)
.strict(true)
.parameters(
JsonValue.from(
Map.of(
"type",
"object",
"properties",
Map.of("customer_id", Map.of("type", "string")),
"required",
List.of("customer_id"),
"additionalProperties",
false)))
.build())
.build())
.addTool(ToolSearchTool.builder().execution(ToolSearchTool.Execution.SERVER).build())
.build();
client.responses().create(params).output().forEach(System.out::println);
来源示例19(ruby)
本段复用的中文释义:译释24、译释25、译释26、译释27。
## [中文] 声明延迟加载的CRM函数并启用tool_search,让模型先发现再使用。
require "openai"
client = OpenAI::Client.new
parameters = {
type: :object,
properties: { customer_id: { type: :string } },
required: ["customer_id"],
additionalProperties: false
}
response = client.responses.create(
model: "gpt-6-astra",
input: "List open orders for customer CUST-12345.",
parallel_tool_calls: false,
tools: [
{
type: :namespace,
name: "crm",
description: "CRM tools for customer lookup and order management.",
tools: [
{
type: :function,
name: "get_customer_profile",
description: "Fetch a customer profile by customer ID.",
parameters: parameters
},
{
type: :function,
name: "list_open_orders",
description: "List open orders for a customer ID.",
defer_loading: true,
parameters: parameters
}
]
},
{ type: :tool_search }
]
)
puts(response.output)
函数调用
调用自己的函数。示例的用户问题是“巴黎今天天气怎么样?”,函数定义接收城市和国家位置;这里展示工具配置和模型输出,不等于应用已经执行了天气服务。
来源示例20(javascript)
程序中的自然语言译释14:
获取指定地点的当前温度。
程序中的自然语言译释16:
城市和国家,例如哥伦比亚的波哥大。
程序中的自然语言译释28:
巴黎今天天气如何?
// [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
import OpenAI from "openai";
const client = new OpenAI();
const tools = [
{
type: "function",
name: "get_weather",
description: "Get current temperature for a given location.",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "City and country e.g. Bogotá, Colombia",
},
},
required: ["location"],
additionalProperties: false,
},
strict: true,
},
];
const response = await client.responses.create({
model: "gpt-6-astra",
input: [
{ role: "user", content: "What is the weather like in Paris today?" },
],
tools,
});
console.log(response.output[0]);
来源示例21(python)
本段复用的中文释义:译释14、译释16、译释28。
## [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
from openai import OpenAI
client = OpenAI()
tools = [
{
"type": "function",
"name": "get_weather",
"description": "Get current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia",
}
},
"required": ["location"],
"additionalProperties": False,
},
"strict": True,
},
]
response = client.responses.create(
model="gpt-6-astra",
input=[
{"role": "user", "content": "What is the weather like in Paris today?"},
],
tools=tools,
)
print(response.output[0].to_json())
来源示例22(go)
本段复用的中文释义:译释14、译释16、译释28。
// [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{
"type": "string",
"description": "City and country e.g. Bogotá, Colombia",
},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := responses.ToolParamOfFunction("get_weather", parameters, true)
tool.OfFunction.Description = openai.String("Get current temperature for a given location.")
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{
responses.ResponseInputItemParamOfMessage("What is the weather like in Paris today?", responses.EasyInputMessageRoleUser),
}},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(response.Output)
}
来源示例23(java)
本段复用的中文释义:译释14、译释16、译释28。
// [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("What is the weather like in Paris today?")
.addTool(
FunctionTool.builder()
.name("get_weather")
.description("Get current temperature for a given location.")
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties",
JsonValue.from(
Map.of(
"location",
Map.of(
"type", "string",
"description",
"City and country e.g. Bogotá, Colombia"))))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build())
.build();
client.responses().create(params).output().forEach(System.out::println);
来源示例24(csharp)
本段复用的中文释义:译释14、译释16、译释28。
// [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
ResponseTool.CreateFunctionTool(
functionName: "get_weather",
functionDescription: "Get current temperature for a given location.",
functionParameters: BinaryData.FromString(
"""
{
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia"
}
},
"required": ["location"],
"additionalProperties": false
}
"""
),
strictModeEnabled: true
)
);
options.InputItems.Add(
ResponseItem.CreateUserMessageItem("What is the weather like in Paris today?")
);
ResponseResult response = await client.CreateResponseAsync(options);
foreach (ResponseItem outputItem in response.OutputItems)
{
if (outputItem is FunctionCallResponseItem functionCall)
{
Console.WriteLine(
$"{functionCall.FunctionName}({functionCall.FunctionArguments})"
);
}
else if (outputItem is MessageResponseItem message)
{
foreach (ResponseContentPart content in message.Content)
{
if (content.Kind == ResponseContentPartKind.OutputText)
{
Console.WriteLine(content.Text);
}
else if (content.Kind == ResponseContentPartKind.Refusal)
{
Console.WriteLine(content.Refusal);
}
}
}
}
来源示例25(ruby)
本段复用的中文释义:译释14、译释16、译释28。
## [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
require "openai"
openai = OpenAI::Client.new
tools = [
{
type: "function",
name: "get_weather",
description: "Get current temperature for a given location.",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "City and country e.g. Bogotá, Colombia"
}
},
required: ["location"],
additionalProperties: false
},
strict: true
}
]
response = openai.responses.create(
model: "gpt-6-astra",
input: [
{
role: "user",
content: "What is the weather like in Paris today?"
}
],
tools: tools
)
puts(response.output.fetch(0).to_json)
来源示例26(bash)
本段复用的中文释义:译释14、译释16、译释28。
## [中文] 配置get_weather函数工具;此段展示请求和输出,不包含真实天气服务的执行闭环。
curl -X POST https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": [
{"role": "user", "content": "What is the weather like in Paris today?"}
],
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia"
}
},
"required": ["location"],
"additionalProperties": false
},
"strict": true
}
]
}'
远程MCP
调用远程MCP服务器。示例要求“搜索OpenAI文档中的Responses API流式输出,返回相关链接”。
来源示例27(bash)
程序中的自然语言译释29:
在OpenAI文档中搜索Responses API流式输出,并返回相关链接。
程序中的自然语言译释30:
搜索并读取公开的OpenAI文档。
## [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "never"
}
],
"input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
}'
来源示例28(javascript)
本段复用的中文释义:译释29、译释30。
// [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
import OpenAI from "openai";
const client = new OpenAI();
const resp = await client.responses.create({
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: "never",
},
],
input:
"Search the OpenAI docs for Responses API streaming and return the relevant links.",
});
console.log(resp.output_text);
来源示例29(python)
本段复用的中文释义:译释29、译释30。
## [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "mcp",
"server_label": "openai_docs",
"server_description": "Search and read the public OpenAI documentation.",
"server_url": "https://developers.openai.com/mcp",
"require_approval": "never",
},
],
input="Search the OpenAI docs for Responses API streaming and return the relevant links.",
)
print(resp.output_text)
来源示例30(go)
本段复用的中文释义:译释29、译释30。
// [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolParamOfMcp("openai_docs")
tool.OfMcp.ServerDescription = openai.String("Search and read the public OpenAI documentation.")
tool.OfMcp.ServerURL = openai.String("https://developers.openai.com/mcp")
tool.OfMcp.RequireApproval = responses.ToolMcpRequireApprovalUnionParam{OfMcpToolApprovalSetting: openai.String("never")}
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Search the OpenAI docs for Responses API streaming and return the relevant links.")},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
}
来源示例31(java)
本段复用的中文释义:译释29、译释30。
// [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.Tool;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input(
"Search the OpenAI docs for Responses API streaming and return the relevant links.")
.addTool(
Tool.Mcp.builder()
.serverLabel("openai_docs")
.serverDescription("Search and read the public OpenAI documentation.")
.serverUrl("https://developers.openai.com/mcp")
.requireApproval(Tool.Mcp.RequireApproval.McpToolApprovalSetting.NEVER)
.build())
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
来源示例32(csharp)
本段复用的中文释义:译释29。
// [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
ResponseTool.CreateMcpTool(
serverLabel: "openai_docs",
serverUri: new Uri("https://developers.openai.com/mcp"),
toolCallApprovalPolicy: DefaultMcpToolCallApprovalPolicy.NeverRequireApproval
)
);
options.InputItems.Add(ResponseItem.CreateUserMessageItem("Search the OpenAI docs for Responses API streaming and return the relevant links."));
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());
来源示例33(ruby)
本段复用的中文释义:译释29、译释30。
## [中文] 连接公开文档MCP并查询流式文档;never仅是此公开只读示例的审批设置。
require "openai"
openai = OpenAI::Client.new
response = openai.responses.create(
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "openai_docs",
server_description: "Search and read the public OpenAI documentation.",
server_url: "https://developers.openai.com/mcp",
require_approval: "never"
}
],
input: "Search the OpenAI docs for Responses API streaming and return the relevant links."
)
puts(response.output_text)
可用工具
| 工具 | 用途 |
|---|---|
| 函数调用 | 调用自定义代码,获得额外数据和能力 |
| 网页搜索 | 把互联网数据纳入响应生成 |
| 远程MCP服务器 | 通过模型上下文协议服务器提供新能力 |
| 技能 | 在托管Shell环境上传并复用带版本的技能包 |
| Shell | 在托管容器或自己的本地运行时执行命令 |
| 计算机操作 | 构建控制计算机界面的智能体工作流 |
| 图像生成 | 使用GPT Image生成或编辑图像 |
| 文件搜索 | 搜索上传文件,为响应提供上下文 |
| 工具搜索 | 动态向上下文加载相关工具,优化词元使用 |
| 程序化工具调用 | 让模型编写并运行JavaScript来编排工具调用 |
在API中使用
请求生成模型响应时,通常在 tools 参数中指定配置以启用工具。不同工具的配置要求不同,参见可用工具。
模型根据提示词自动判断是否使用已配置工具。例如问题超出训练数据截止时间,且启用了网页搜索时,模型通常会调用搜索获取新信息。
高级工作流也可在交互过程中加载更多工具定义。例如工具搜索可延迟加载函数定义,直到模型判断需要。请求中的 tool_choice 参数可以显式控制或引导工具选择行为。
Agents API
Agents API替你运行智能体循环。在 agent.tools 中配置工具,在应用中处理函数调用;工具需要执行环境时连接沙箱。
通过Functions调用应用代码,通过MCP connections连接工具服务器,通过沙箱配置提供执行环境。程序化工具调用默认启用;技能通过沙箱能力目录发现。
在Agents SDK中使用
工具语义保持相同,但配置位置从单个Responses请求移至智能体定义与工作流设计。
- 某个专职智能体需要自行调用时,直接附加托管工具、函数工具或托管MCP工具。
- 管理智能体需要保留面向用户的回答控制权时,把专职智能体暴露为工具。
- 即使SDK负责工具决策,Shell、应用补丁和计算机操作的执行框架仍应由自己的运行时承担。
将本地逻辑包装为函数工具:
来源示例34(javascript)
程序中的自然语言译释31:
获取指定城市的天气。
// [中文] 将本地天气逻辑包装成Agents SDK函数工具,参数由模式定义。
import { tool } from "@openai/agents";
import { z } from "zod";
const getWeatherTool = tool({
name: "get_weather",
description: "Get the weather for a given city.",
parameters: z.object({ city: z.string() }),
async execute({ city }) {
return `The weather in ${city} is sunny.`;
},
});
来源示例35(python)
本段复用的中文释义:译释31。
## [中文] 将本地天气逻辑包装成Agents SDK函数工具,参数由模式定义。
from agents import function_tool
@function_tool
def get_weather(city: str) -> str:
"""Get the weather for a given city."""
return f"The weather in {city} is sunny."
将专职智能体暴露为工具。示例中的专职智能体负责“为提供的文本生成简洁摘要”。
来源示例36(javascript)
程序中的自然语言译释32:
为提供的文本生成简洁摘要。
// [中文] 创建摘要专职智能体并暴露为管理智能体的工具;此段是定义,不是一次完整运行。
import { Agent } from "@openai/agents";
const summarizer = new Agent({
name: "Summarizer",
instructions: "Generate a concise summary of the supplied text.",
});
const mainAgent = new Agent({
name: "Research assistant",
tools: [
summarizer.asTool({
toolName: "summarize_text",
toolDescription: "Generate a concise summary of the supplied text.",
}),
],
});
来源示例37(python)
本段复用的中文释义:译释32。
## [中文] 创建摘要专职智能体并暴露为管理智能体的工具;此段是定义,不是一次完整运行。
from agents import Agent
summarizer = Agent(
name="Summarizer",
instructions="Generate a concise summary of the supplied text.",
)
main_agent = Agent(
name="Research assistant",
tools=[
summarizer.as_tool(
tool_name="summarize_text",
tool_description="Generate a concise summary of the supplied text.",
)
],
)
设计单个专职智能体时参见智能体定义;工具影响任务归属时参见编排与交接;涉及审批时参见防护与人工审核;能力来自MCP时参见集成与可观测性。