codecamp

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时参见集成与可观测性。

OpenAI 函数调用
OpenAI 应用补丁
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }