> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具调用

Toolcall（或叫 Function Calling）是阶跃星辰开放平台提供的一项高级功能，它使模型能够根据用户的需求，智能地选择并调用合适的外部工具或函数来完成特定的任务。通过 Toolcall API，开发者可以扩展模型的能力，使其能够处理更广泛的应用场景，并提供更丰富的功能和服务。下面是一个简单的工具调用的请求 JSON 例子, 在这个对象中，必须包含三个关键参数：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"model": "step-5-preview",
	"messages": [
		{
			"role": "user",
			"content": "小跃跃，你能为我计算 (80 + 20) / 5 吗？"
		}
	],
	"tools": [
		{
			"type": "function",
			"function": {
				"name": "Calculator",
				"description": "这个阶跃星辰开放平台 API 提供基本的算术运算：加法、减法、乘法和除法。",
				"parameters": {
					"type": "object",
					"properties": {
						"formula": {
							"type": "string",
							"description": "需要计算的公式。仅支持整数。有效的运算符包括 +、-、*、/ 和括号。例如，(1 + 2) * 3。"
						}
					}
				}
			}
		}
	]
}
```

## model，模型名称

以下模型支持工具调用，推荐优先使用第一档：

**推荐**

* `step-5-preview`、`step-3.7-flash`、`step-3.5-flash`、`step-3.5-flash-2603`

**仅 Step Plan 通道**

* `step-router-v1`（详见 [Step Plan 推理模型接入](https://platform.stepfun.com/docs/zh/step-plan/integrations/reasoning-api.md)）

**其他兼容**

* `step-1o-turbo-vision`

## 官方工具列表

以下是由阶跃星辰支持的官方工具，仅需配置即可实现相关能力：

* [互联网搜索](https://platform.stepfun.com/docs/zh/guides/developer/web-search.md)：推荐使用网页搜索 API（`POST /v1/search`）。Chat Completions 内置 `web_search` 工具在 `step-5-preview` 上不可用。
* [知识库搜索](https://platform.stepfun.com/docs/zh/guides/developer/retrieval.md)：上传文本到知识库中，并完成对知识库内容的搜索，帮助大模型消除幻觉

## tools，工具函数列表

通过 `tools` 参数告知模型本地支持的函数列表。每个成员对象包含 `type` 和 `function` 两个字段：`type` 当前仅支持 `function`，`function` 对象包含 `name`、`description` 和 `parameters`。函数数量建议控制在合理规模，过多的函数定义会消耗较多 prompt token，并可能降低模型的命中准确率。

* **name**（函数名称）：建议使用英文字母、数字、下划线与连字符，遵循正则 `^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$`，长度不超过 64 字符。使用语义化的英文名更易被模型识别。
* **description**（功能介绍）：支持中英文，用于告诉模型此函数的用途与适用场景，便于模型判断何时调用。描述越清晰，模型命中越准确。
* **parameters**（参数定义）：根节点 `type` 必须为 `object`；`properties` 内每个字段按 [JSON Schema](https://json-schema.org/understanding-json-schema/reference/type) 规范描述其 `type` 和 `description`。若参数必填，请在 `required` 数组中列出。

## messages，上下文消息体

请求消息体结构参考 [Chat Completion 请求参数](https://platform.stepfun.com/docs/zh/api-reference/chat/chat-completion-create.md#请求参数)。当模型返回 `tool_calls` 后，开发者在本地执行对应函数，再通过 `role: "tool"` 的消息（携带 `tool_call_id`）将结果回传至下一轮请求，模型据此生成最终回答。

## 示例

> [tab] python
>
> ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> from openai import OpenAI
>
> client = OpenAI(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com/v1")
>
> completion = client.chat.completions.create(
>     model="step-5-preview",
>     messages=[
>         {
>             "role": "user",
>             "content": "你能为我计算(80 + 20) / 5 吗？"
>         }
>     ],
>     tools=[
>         {
>             "type": "function",
>             "function": {
>                 "name": "Calculator",
>                 "description": "这个阶跃星辰开放平台API提供基本的算术运算：加法、减法、乘法和除法。",
>                 "parameters": {
>                     "type": "object",
>                     "properties": {
>                         "formula": {
>                             "type": "string",
>                             "description": "需要计算的公式。仅支持整数。有效的运算符包括+、-、*、/和括号。例如，'(1 + 2) * 3'。"
>                         }
>                     }
>                 }
>             }
>         }
>     ]
> )
>
> print(completion)
> ```

> [tab] js
>
> ```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> import OpenAI from "openai";
>
> const openai = new OpenAI({
>     apiKey: "YOUR_STEP_API_KEY",
>     baseURL: "https://api.stepfun.com/v1"
> });
>
> async function main() {
>     const completion = await openai.chat.completions.create({
>         model: "step-5-preview",
>         messages: [
>             {
>                 "role": "user",
>                 "content": "你能为我计算(80 + 20) / 5 吗？"
>             }
>         ],
>         tools: [
>             {
>                 "type": "function",
>                 "function": {
>                     "name": "Calculator",
>                     "description": "这个阶跃星辰开放平台API提供基本的算术运算：加法、减法、乘法和除法。",
>                     "parameters": {
>                         "type": "object",
>                         "properties": {
>                             "formula": {
>                                 "type": "string",
>                                 "description": "需要计算的公式。仅支持整数。有效的运算符包括+、-、*、/和括号。例如，'(1 + 2) * 3'。"
>                             }
>                         }
>                     }
>                 }
>             }
>         ]
>     });
>
>     console.log(JSON.stringify(completion));
> }
>
> main();
> ```

> [tab] curl
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> curl https://api.stepfun.com/v1/chat/completions \
>   -H "Content-Type: application/json" \
>   -H "Authorization: Bearer $STEP_API_KEY" \
>   -d '{
>     "model": "step-5-preview",
>     "messages": [
>       {
>         "role": "user",
>         "content": "你能为我计算(80 + 20) / 5 吗？"
>       }
>     ],
>     "tools": [
>       {
>         "type": "function",
>         "function": {
>           "name": "Calculator",
>           "description": "这个阶跃星辰开放平台API提供基本的算术运算：加法、减法、乘法和除法。",
>           "parameters": {
>             "type": "object",
>             "properties": {
>               "formula": {
>                 "type": "string",
>                 "description": "需要计算的公式。仅支持整数。有效的运算符包括+、-、*、/和括号。例如: (1 + 2) * 3。"
>               }
>             }
>           }
>         }
>       }
>     ]
>   }'
> ```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "b7b56af0-52a6-483f-a589-948182676a1b",
  "object": "chat.completion",
  "created": 1717744611,
  "model": "step-5-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_ybVBO_JASgipgJH8xWbhKg",
            "type": "function",
            "function": {
              "name": "Calculator",
              "arguments": "{\"formula\": \"(80 + 20) / 5\"}"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 151,
    "completion_tokens": 25,
    "total_tokens": 176
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.