你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
构建超越对话的 AI 助手, 它可以调用函数来执行操作。 助手决定何时需要函数,然后执行该函数,并将结果馈送回。 所有内容都使用 Foundry 本地 SDK 在本地运行。
本教程中,您将学习如何:
- 设置项目并安装 Foundry 本地 SDK
- 定义助手可以调用的工具
- 发送触发工具使用的消息
- 执行该工具并将结果返回到模型
- 处理完整的工具调用循环
- 清理资源
先决条件
- 至少具有 8 GB RAM 的 Windows、macOS 或 Linux 计算机。
示例存储库
可以在 Foundry 示例GitHub存储库中找到本文的完整示例代码。 若要克隆存储库并导航到示例,请使用:
git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/csharp/foundry-local/tutorial-tool-calling
安装软件包
dotnet add package Microsoft.AI.Foundry.Local
dotnet add package OpenAI
GitHub存储库中的 C# 示例是预配置项目。 如果要从头开始生成,则应阅读 Foundry Local SDK 参考 ,详细了解如何使用 Foundry Local 设置 C# 项目。
定义工具
工具调用允许模型请求代码运行函数并返回结果。 将可用工具定义为描述每个函数的名称、用途和参数的 JSON 架构列表。
打开
Program.cs并添加以下工具定义:// --- Tool definitions and implementations --- var toolDefinitions = new[] { new { Name = "get_weather", Description = "Get the current weather for a location", Schema = """ { "type": "object", "properties": { "location": { "type": "string", "description": "The city or location" }, "unit": { "type": "string", "description": "Temperature unit", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } """ }, new { Name = "calculate", Description = "Perform a math calculation", Schema = """ { "type": "object", "properties": { "expression": { "type": "string", "description": "The math expression to evaluate" } }, "required": ["expression"] } """ } }; string ExecuteTool(string functionName, JsonElement arguments) { switch (functionName) { case "get_weather": var location = arguments.GetProperty("location").GetString() ?? "unknown"; var unit = arguments.TryGetProperty("unit", out var u) ? u.GetString() ?? "celsius" : "celsius"; var temp = unit == "celsius" ? 22 : 72; return JsonSerializer.Serialize(new { location, temperature = temp, unit, condition = "Sunny" }); case "calculate": var expression = arguments.GetProperty("expression").GetString() ?? ""; try { var result = new System.Data.DataTable().Compute(expression, null); return JsonSerializer.Serialize(new { expression, result = result?.ToString() }); } catch (Exception ex) { return JsonSerializer.Serialize(new { error = ex.Message }); } default: return JsonSerializer.Serialize(new { error = $"Unknown function: {functionName}" }); } }每个工具定义都包含一个
name、一个帮助模型决定何时使用它的description以及一个描述预期输入的parameters架构。添加实现每个工具的 C# 方法:
// --- Tool definitions and implementations --- var toolDefinitions = new[] { new { Name = "get_weather", Description = "Get the current weather for a location", Schema = """ { "type": "object", "properties": { "location": { "type": "string", "description": "The city or location" }, "unit": { "type": "string", "description": "Temperature unit", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } """ }, new { Name = "calculate", Description = "Perform a math calculation", Schema = """ { "type": "object", "properties": { "expression": { "type": "string", "description": "The math expression to evaluate" } }, "required": ["expression"] } """ } }; string ExecuteTool(string functionName, JsonElement arguments) { switch (functionName) { case "get_weather": var location = arguments.GetProperty("location").GetString() ?? "unknown"; var unit = arguments.TryGetProperty("unit", out var u) ? u.GetString() ?? "celsius" : "celsius"; var temp = unit == "celsius" ? 22 : 72; return JsonSerializer.Serialize(new { location, temperature = temp, unit, condition = "Sunny" }); case "calculate": var expression = arguments.GetProperty("expression").GetString() ?? ""; try { var result = new System.Data.DataTable().Compute(expression, null); return JsonSerializer.Serialize(new { expression, result = result?.ToString() }); } catch (Exception ex) { return JsonSerializer.Serialize(new { error = ex.Message }); } default: return JsonSerializer.Serialize(new { error = $"Unknown function: {functionName}" }); } }模型不会直接运行这些函数。 它返回具有函数名称和参数的工具调用请求,代码执行该函数。
发送触发工具使用的消息
初始化 Foundry 本地 SDK,加载模型,并发送一条消息,通过调用工具使模型可以应答。
// --- Main application ---
var config = new Configuration
{
AppName = "foundry_local_samples",
LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information
};
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();
await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
var currentEp = "";
await mgr.DownloadAndRegisterEpsAsync((epName, percent) =>
{
if (epName != currentEp)
{
if (currentEp != "") Console.WriteLine();
currentEp = epName;
}
Console.Write($"\r {epName.PadRight(30)} {percent,6:F1}%");
});
if (currentEp != "") Console.WriteLine();
var catalog = await mgr.GetCatalogAsync();
var model = await catalog.GetModelAsync("qwen2.5-0.5b")
?? throw new Exception("Model not found");
await model.DownloadAsync(progress =>
{
Console.Write($"\rDownloading model: {progress:F2}%");
if (progress >= 100f) Console.WriteLine();
});
await model.LoadAsync();
Console.WriteLine("Model loaded and ready.");
using var chatSession = new ChatSession(model);
chatSession.SetOptions(new RequestOptions { ToolChoice = ToolChoice.Auto });
foreach (var tool in toolDefinitions)
{
chatSession.AddToolDefinition(tool.Name, tool.Description, tool.Schema);
}
当模型确定需要工具时,响应包含 ToolCalls 而不是常规短信。 下一步演示如何检测和处理这些调用。
执行该工具并返回结果
在模型使用工具调用进行响应后,可以提取函数名称和参数,运行函数,并将结果发送回。
Console.WriteLine("\nTool-calling assistant ready! Type 'quit' to exit.\n");
while (true)
{
Console.Write("You: ");
var userInput = Console.ReadLine();
if (string.IsNullOrWhiteSpace(userInput) ||
userInput.Equals("quit", StringComparison.OrdinalIgnoreCase) ||
userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
{
break;
}
using var request = new Request();
if (chatSession.TurnCount == 0)
{
request.AddItem(MessageItem.System(
"You are a helpful assistant with access to tools. Use them when needed."));
}
request.AddItem(MessageItem.User(userInput));
using var response = await chatSession.ProcessRequestAsync(request, ct);
var toolCalls = response.OfType<ToolCallItem>()
.Select(call => (call.CallId, call.Name, call.Arguments))
.ToList();
if (toolCalls.Count > 0)
{
using var toolRequest = new Request();
foreach (var toolCall in toolCalls)
{
using var argumentsDocument = JsonDocument.Parse(toolCall.Arguments);
var arguments = argumentsDocument.RootElement;
Console.WriteLine($" Tool call: {toolCall.Name}({arguments})");
var result = ExecuteTool(toolCall.Name, arguments);
toolRequest.AddItem(new ToolResultItem(toolCall.CallId, result));
}
using var finalResponse = await chatSession.ProcessRequestAsync(toolRequest, ct);
var answer = GetResponseText(finalResponse);
Console.WriteLine($"Assistant: {answer}\n");
}
else
{
Console.WriteLine($"Assistant: {GetResponseText(response)}\n");
}
}
chatSession.Dispose();
await model.UnloadAsync();
Console.WriteLine("Model unloaded. Goodbye!");
工具调用循环中的关键步骤包括:
-
检测工具调用 - 检查
response.Choices[0].Message.ToolCalls。 - 执行函数 - 分析参数并调用本地函数。
-
返回结果 - 添加消息,其中包含角色
tool和匹配项ToolCallId。 - 获取最终答案 - 模型使用工具结果生成自然响应。
处理完整的工具调用循环
下面是将工具定义、SDK 初始化和工具调用循环合并到单个可运行文件中的完整应用程序。
将 Program.cs 的内容替换为完整的代码:
using System.Text.Json;
using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging;
CancellationToken ct = CancellationToken.None;
// --- Tool definitions and implementations ---
var toolDefinitions = new[]
{
new
{
Name = "get_weather",
Description = "Get the current weather for a location",
Schema =
"""
{
"type": "object",
"properties": {
"location": { "type": "string", "description": "The city or location" },
"unit": {
"type": "string",
"description": "Temperature unit",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
"""
},
new
{
Name = "calculate",
Description = "Perform a math calculation",
Schema =
"""
{
"type": "object",
"properties": {
"expression": { "type": "string", "description": "The math expression to evaluate" }
},
"required": ["expression"]
}
"""
}
};
string ExecuteTool(string functionName, JsonElement arguments)
{
switch (functionName)
{
case "get_weather":
var location = arguments.GetProperty("location").GetString() ?? "unknown";
var unit = arguments.TryGetProperty("unit", out var u)
? u.GetString() ?? "celsius"
: "celsius";
var temp = unit == "celsius" ? 22 : 72;
return JsonSerializer.Serialize(new
{
location,
temperature = temp,
unit,
condition = "Sunny"
});
case "calculate":
var expression = arguments.GetProperty("expression").GetString() ?? "";
try
{
var result = new System.Data.DataTable().Compute(expression, null);
return JsonSerializer.Serialize(new { expression, result = result?.ToString() });
}
catch (Exception ex)
{
return JsonSerializer.Serialize(new { error = ex.Message });
}
default:
return JsonSerializer.Serialize(new { error = $"Unknown function: {functionName}" });
}
}
// --- Main application ---
var config = new Configuration
{
AppName = "foundry_local_samples",
LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information
};
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();
await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;
var currentEp = "";
await mgr.DownloadAndRegisterEpsAsync((epName, percent) =>
{
if (epName != currentEp)
{
if (currentEp != "") Console.WriteLine();
currentEp = epName;
}
Console.Write($"\r {epName.PadRight(30)} {percent,6:F1}%");
});
if (currentEp != "") Console.WriteLine();
var catalog = await mgr.GetCatalogAsync();
var model = await catalog.GetModelAsync("qwen2.5-0.5b")
?? throw new Exception("Model not found");
await model.DownloadAsync(progress =>
{
Console.Write($"\rDownloading model: {progress:F2}%");
if (progress >= 100f) Console.WriteLine();
});
await model.LoadAsync();
Console.WriteLine("Model loaded and ready.");
using var chatSession = new ChatSession(model);
chatSession.SetOptions(new RequestOptions { ToolChoice = ToolChoice.Auto });
foreach (var tool in toolDefinitions)
{
chatSession.AddToolDefinition(tool.Name, tool.Description, tool.Schema);
}
Console.WriteLine("\nTool-calling assistant ready! Type 'quit' to exit.\n");
while (true)
{
Console.Write("You: ");
var userInput = Console.ReadLine();
if (string.IsNullOrWhiteSpace(userInput) ||
userInput.Equals("quit", StringComparison.OrdinalIgnoreCase) ||
userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
{
break;
}
using var request = new Request();
if (chatSession.TurnCount == 0)
{
request.AddItem(MessageItem.System(
"You are a helpful assistant with access to tools. Use them when needed."));
}
request.AddItem(MessageItem.User(userInput));
using var response = await chatSession.ProcessRequestAsync(request, ct);
var toolCalls = response.OfType<ToolCallItem>()
.Select(call => (call.CallId, call.Name, call.Arguments))
.ToList();
if (toolCalls.Count > 0)
{
using var toolRequest = new Request();
foreach (var toolCall in toolCalls)
{
using var argumentsDocument = JsonDocument.Parse(toolCall.Arguments);
var arguments = argumentsDocument.RootElement;
Console.WriteLine($" Tool call: {toolCall.Name}({arguments})");
var result = ExecuteTool(toolCall.Name, arguments);
toolRequest.AddItem(new ToolResultItem(toolCall.CallId, result));
}
using var finalResponse = await chatSession.ProcessRequestAsync(toolRequest, ct);
var answer = GetResponseText(finalResponse);
Console.WriteLine($"Assistant: {answer}\n");
}
else
{
Console.WriteLine($"Assistant: {GetResponseText(response)}\n");
}
}
chatSession.Dispose();
await model.UnloadAsync();
Console.WriteLine("Model unloaded. Goodbye!");
运行工具调用助手:
dotnet run
会看到类似于以下内容的输出:
Downloading model: 100.00%
Model loaded and ready.
Tool-calling assistant ready! Type 'quit' to exit.
You: What's the weather like today?
Tool call: get_weather({"location":"current location"})
Assistant: The weather today is sunny with a temperature of 22°C.
You: What is 245 * 38?
Tool call: calculate({"expression":"245 * 38"})
Assistant: 245 multiplied by 38 equals 9,310.
You: quit
Model unloaded. Goodbye!
模型根据用户的消息决定何时调用工具。 对于天气问题,它调用 get_weather,对于数学问题,它调用 calculate,而对于常规问题,它直接响应,不需要调用任何工具。
示例存储库
本文的完整示例代码在 foundry-samples GitHub 存储库中提供。 若要克隆存储库并导航到示例,请使用:
git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/javascript/foundry-local/tutorial-tool-calling
安装软件包
npm install foundry-local-sdk openai
定义工具
工具调用允许模型请求代码运行函数并返回结果。 将可用工具定义为描述每个函数的名称、用途和参数的 JSON 架构列表。
创建名为 的文件
index.js。添加以下工具定义:
// --- Tool definitions --- const tools = [ { name: 'get_weather', description: 'Get the current weather for a location', jsonSchema: JSON.stringify({ type: 'object', properties: { location: { type: 'string', description: 'The city or location' }, unit: { type: 'string', enum: ['celsius', 'fahrenheit'], description: 'Temperature unit' } }, required: ['location'] }) }, { name: 'calculate', description: 'Perform a math calculation', jsonSchema: JSON.stringify({ type: 'object', properties: { expression: { type: 'string', description: 'The math expression to evaluate' } }, required: ['expression'] }) } ]; // --- Tool implementations --- function getWeather(location, unit = 'celsius') { return { location, temperature: unit === 'celsius' ? 22 : 72, unit, condition: 'Sunny' }; } function calculate(expression) { // Input is validated against a strict allowlist of numeric/math characters, // making this safe from code injection in this tutorial context. const allowed = /^[0-9+\-*/(). ]+$/; if (!allowed.test(expression)) { return { error: 'Invalid expression' }; } try { const result = Function( `"use strict"; return (${expression})` )(); return { expression, result }; } catch (err) { return { error: err.message }; } } const toolFunctions = { get_weather: (args) => getWeather(args.location, args.unit), calculate: (args) => calculate(args.expression) };每个工具定义都包含一个
name、一个帮助模型决定何时使用它的description以及一个描述预期输入的parameters架构。添加实现每个工具的 JavaScript 函数:
// --- Tool definitions --- const tools = [ { name: 'get_weather', description: 'Get the current weather for a location', jsonSchema: JSON.stringify({ type: 'object', properties: { location: { type: 'string', description: 'The city or location' }, unit: { type: 'string', enum: ['celsius', 'fahrenheit'], description: 'Temperature unit' } }, required: ['location'] }) }, { name: 'calculate', description: 'Perform a math calculation', jsonSchema: JSON.stringify({ type: 'object', properties: { expression: { type: 'string', description: 'The math expression to evaluate' } }, required: ['expression'] }) } ]; // --- Tool implementations --- function getWeather(location, unit = 'celsius') { return { location, temperature: unit === 'celsius' ? 22 : 72, unit, condition: 'Sunny' }; } function calculate(expression) { // Input is validated against a strict allowlist of numeric/math characters, // making this safe from code injection in this tutorial context. const allowed = /^[0-9+\-*/(). ]+$/; if (!allowed.test(expression)) { return { error: 'Invalid expression' }; } try { const result = Function( `"use strict"; return (${expression})` )(); return { expression, result }; } catch (err) { return { error: err.message }; } } const toolFunctions = { get_weather: (args) => getWeather(args.location, args.unit), calculate: (args) => calculate(args.expression) };模型不会直接运行这些函数。 它返回具有函数名称和参数的工具调用请求,代码执行该函数。
发送触发工具使用的消息
初始化 Foundry 本地 SDK,加载模型,并发送一条消息,通过调用工具使模型可以应答。
// --- Main application ---
const manager = FoundryLocalManager.create({
appName: 'foundry_local_samples',
logLevel: 'info'
});
// Download and register all execution providers.
let currentEp = '';
await manager.downloadAndRegisterEps((epName, percent) => {
if (epName !== currentEp) {
if (currentEp !== '') process.stdout.write('\n');
currentEp = epName;
}
process.stdout.write(`\r ${epName.padEnd(30)} ${percent.toFixed(1).padStart(5)}%`);
});
if (currentEp !== '') process.stdout.write('\n');
const model = await manager.catalog.getModel('qwen2.5-0.5b');
await model.download((progress) => {
process.stdout.write(
`\rDownloading model: ${progress.toFixed(2)}%`
);
});
console.log('\nModel downloaded.');
await model.load();
console.log('Model loaded and ready.');
const chatSession = new ChatSession(model);
for (const tool of tools) {
chatSession.addToolDefinition(tool);
}
let firstTurn = true;
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
const askQuestion = (prompt) =>
new Promise((resolve) => {
if (rl.closed) return resolve('quit');
const onClose = () => resolve('quit');
rl.once('close', onClose);
rl.question(prompt, (answer) => {
rl.off('close', onClose);
resolve(answer);
});
});
console.log(
'\nTool-calling assistant ready! Type \'quit\' to exit.\n'
);
while (true) {
const userInput = await askQuestion('You: ');
if (
userInput.trim().toLowerCase() === 'quit' ||
userInput.trim().toLowerCase() === 'exit'
) {
break;
}
const request = new Request().setOptions({ toolChoice: 'auto' });
if (firstTurn) {
request.addItem(Item.systemMessage(
'You are a helpful assistant with access to tools. ' +
'Use them when needed to answer questions accurately.'
));
firstTurn = false;
}
request.addItem(Item.userMessage(userInput));
const response = await chatSession.processRequest(request);
const answer = await processToolCalls(
response, chatSession
);
console.log(`Assistant: ${answer}\n`);
}
chatSession.dispose();
await model.unload();
console.log('Model unloaded. Goodbye!');
rl.close();
当模型确定需要工具时,响应包含 tool_calls 而不是常规短信。 下一步演示如何检测和处理这些调用。
执行该工具并返回结果
在模型使用工具调用进行响应后,可以提取函数名称和参数,运行函数,并将结果发送回。
async function processToolCalls(response, chatSession) {
let currentResponse = response;
while (currentResponse.finishReason === 'toolCalls') {
const toolResults = [];
for (const toolCall of currentResponse.output.filter(
(item) => item.type === 'toolCall'
)) {
const functionName = toolCall.name;
const args = JSON.parse(toolCall.arguments);
console.log(
` Tool call: ${functionName}` +
`(${JSON.stringify(args)})`
);
const implementation = toolFunctions[functionName];
const result = implementation
? implementation(args)
: { error: `Unknown tool: ${functionName}` };
toolResults.push(Item.toolResult(
toolCall.callId,
JSON.stringify(result)
));
}
if (toolResults.length === 0) {
throw new Error('The model requested tools but returned no tool calls.');
}
const followUp = new Request()
.setOptions({ toolChoice: 'auto' });
for (const result of toolResults) {
followUp.addItem(result);
}
currentResponse = await chatSession.processRequest(followUp);
}
return currentResponse.output
.map((item) => item.type === 'message'
? item.content ?? item.parts?.map((part) => part.text ?? '').join('') ?? ''
: item.type === 'text' ? item.text : '')
.join('');
}
工具调用循环中的关键步骤包括:
-
检测工具调用 - 检查
response.choices[0]?.message?.tool_calls。 - 执行函数 - 分析参数并调用本地函数。
-
返回结果 - 添加消息,其中包含角色
tool和匹配项tool_call_id。 - 获取最终答案 - 模型使用工具结果生成自然响应。
处理完整的工具调用循环
下面是将工具定义、SDK 初始化和工具调用循环合并到单个可运行文件中的完整应用程序。
创建一个名为 index.js 并添加以下完整代码的文件:
import {
ChatSession,
FoundryLocalManager,
Item,
Request
} from 'foundry-local-sdk';
import * as readline from 'readline';
// --- Tool definitions ---
const tools = [
{
name: 'get_weather',
description: 'Get the current weather for a location',
jsonSchema: JSON.stringify({
type: 'object',
properties: {
location: {
type: 'string',
description: 'The city or location'
},
unit: {
type: 'string',
enum: ['celsius', 'fahrenheit'],
description: 'Temperature unit'
}
},
required: ['location']
})
},
{
name: 'calculate',
description: 'Perform a math calculation',
jsonSchema: JSON.stringify({
type: 'object',
properties: {
expression: {
type: 'string',
description: 'The math expression to evaluate'
}
},
required: ['expression']
})
}
];
// --- Tool implementations ---
function getWeather(location, unit = 'celsius') {
return {
location,
temperature: unit === 'celsius' ? 22 : 72,
unit,
condition: 'Sunny'
};
}
function calculate(expression) {
// Input is validated against a strict allowlist of numeric/math characters,
// making this safe from code injection in this tutorial context.
const allowed = /^[0-9+\-*/(). ]+$/;
if (!allowed.test(expression)) {
return { error: 'Invalid expression' };
}
try {
const result = Function(
`"use strict"; return (${expression})`
)();
return { expression, result };
} catch (err) {
return { error: err.message };
}
}
const toolFunctions = {
get_weather: (args) => getWeather(args.location, args.unit),
calculate: (args) => calculate(args.expression)
};
async function processToolCalls(response, chatSession) {
let currentResponse = response;
while (currentResponse.finishReason === 'toolCalls') {
const toolResults = [];
for (const toolCall of currentResponse.output.filter(
(item) => item.type === 'toolCall'
)) {
const functionName = toolCall.name;
const args = JSON.parse(toolCall.arguments);
console.log(
` Tool call: ${functionName}` +
`(${JSON.stringify(args)})`
);
const implementation = toolFunctions[functionName];
const result = implementation
? implementation(args)
: { error: `Unknown tool: ${functionName}` };
toolResults.push(Item.toolResult(
toolCall.callId,
JSON.stringify(result)
));
}
if (toolResults.length === 0) {
throw new Error('The model requested tools but returned no tool calls.');
}
const followUp = new Request()
.setOptions({ toolChoice: 'auto' });
for (const result of toolResults) {
followUp.addItem(result);
}
currentResponse = await chatSession.processRequest(followUp);
}
return currentResponse.output
.map((item) => item.type === 'message'
? item.content ?? item.parts?.map((part) => part.text ?? '').join('') ?? ''
: item.type === 'text' ? item.text : '')
.join('');
}
// --- Main application ---
const manager = FoundryLocalManager.create({
appName: 'foundry_local_samples',
logLevel: 'info'
});
// Download and register all execution providers.
let currentEp = '';
await manager.downloadAndRegisterEps((epName, percent) => {
if (epName !== currentEp) {
if (currentEp !== '') process.stdout.write('\n');
currentEp = epName;
}
process.stdout.write(`\r ${epName.padEnd(30)} ${percent.toFixed(1).padStart(5)}%`);
});
if (currentEp !== '') process.stdout.write('\n');
const model = await manager.catalog.getModel('qwen2.5-0.5b');
await model.download((progress) => {
process.stdout.write(
`\rDownloading model: ${progress.toFixed(2)}%`
);
});
console.log('\nModel downloaded.');
await model.load();
console.log('Model loaded and ready.');
const chatSession = new ChatSession(model);
for (const tool of tools) {
chatSession.addToolDefinition(tool);
}
let firstTurn = true;
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
const askQuestion = (prompt) =>
new Promise((resolve) => {
if (rl.closed) return resolve('quit');
const onClose = () => resolve('quit');
rl.once('close', onClose);
rl.question(prompt, (answer) => {
rl.off('close', onClose);
resolve(answer);
});
});
console.log(
'\nTool-calling assistant ready! Type \'quit\' to exit.\n'
);
while (true) {
const userInput = await askQuestion('You: ');
if (
userInput.trim().toLowerCase() === 'quit' ||
userInput.trim().toLowerCase() === 'exit'
) {
break;
}
const request = new Request().setOptions({ toolChoice: 'auto' });
if (firstTurn) {
request.addItem(Item.systemMessage(
'You are a helpful assistant with access to tools. ' +
'Use them when needed to answer questions accurately.'
));
firstTurn = false;
}
request.addItem(Item.userMessage(userInput));
const response = await chatSession.processRequest(request);
const answer = await processToolCalls(
response, chatSession
);
console.log(`Assistant: ${answer}\n`);
}
chatSession.dispose();
await model.unload();
console.log('Model unloaded. Goodbye!');
rl.close();
运行工具调用助手:
node index.js
会看到类似于以下内容的输出:
Downloading model: 100.00%
Model downloaded.
Model loaded and ready.
Tool-calling assistant ready! Type 'quit' to exit.
You: What's the weather like today?
Tool call: get_weather({"location":"current location"})
Assistant: The weather today is sunny with a temperature of 22°C.
You: What is 245 * 38?
Tool call: calculate({"expression":"245 * 38"})
Assistant: 245 multiplied by 38 equals 9,310.
You: quit
Model unloaded. Goodbye!
模型根据用户的消息决定何时调用工具。 对于天气问题,它调用 get_weather,对于数学问题,它调用 calculate,而对于常规问题,它直接响应,不需要调用任何工具。
示例存储库
本文的完整示例代码在 foundry-samples GitHub 存储库中提供。 若要克隆存储库并导航到示例,请使用:
git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/python/foundry-local/tutorial-tool-calling
安装软件包
pip install foundry-local-sdk openai
定义工具
工具调用允许模型请求代码运行函数并返回结果。 将可用工具定义为描述每个函数的名称、用途和参数的 JSON 架构列表。
创建一个名为 main.py 的文件并添加以下工具定义:
# --- Tool definitions ---
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city or location",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit",
},
},
"required": ["location"],
},
},
{
"name": "calculate",
"description": "Perform a math calculation",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "The math expression to evaluate",
}
},
"required": ["expression"],
},
},
]
# --- Tool implementations ---
def get_weather(location, unit="celsius"):
"""Simulate a weather lookup."""
return {
"location": location,
"temperature": 22 if unit == "celsius" else 72,
"unit": unit,
"condition": "Sunny",
}
def calculate(expression):
"""Evaluate a math expression safely."""
allowed = set("0123456789+-*/(). ")
if not all(character in allowed for character in expression):
return {"error": "Invalid expression"}
try:
result = eval(expression, {"__builtins__": {}}, {})
return {"expression": expression, "result": result}
except Exception as error:
return {"error": str(error)}
tool_functions = {"get_weather": get_weather, "calculate": calculate}
每个工具定义都包含一个name、一个帮助模型决定何时使用它的description以及一个描述预期输入的parameters架构。
接下来,添加实现每个工具的Python函数:
# --- Tool definitions ---
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city or location",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit",
},
},
"required": ["location"],
},
},
{
"name": "calculate",
"description": "Perform a math calculation",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "The math expression to evaluate",
}
},
"required": ["expression"],
},
},
]
# --- Tool implementations ---
def get_weather(location, unit="celsius"):
"""Simulate a weather lookup."""
return {
"location": location,
"temperature": 22 if unit == "celsius" else 72,
"unit": unit,
"condition": "Sunny",
}
def calculate(expression):
"""Evaluate a math expression safely."""
allowed = set("0123456789+-*/(). ")
if not all(character in allowed for character in expression):
return {"error": "Invalid expression"}
try:
result = eval(expression, {"__builtins__": {}}, {})
return {"expression": expression, "result": result}
except Exception as error:
return {"error": str(error)}
tool_functions = {"get_weather": get_weather, "calculate": calculate}
模型不会直接运行这些函数。 它返回具有函数名称和参数的工具调用请求,代码执行该函数。
发送触发工具使用的消息
初始化 Foundry 本地 SDK,加载模型,并发送一条消息,通过调用工具使模型可以应答。
def main():
# Initialize the Foundry Local SDK
config = Configuration(app_name="foundry_local_samples")
FoundryLocalManager.initialize(config)
manager = FoundryLocalManager.instance
# Discover and register execution providers that are not already available.
missing_eps = [ep.name for ep in manager.discover_eps() if not ep.is_registered]
if missing_eps:
manager.download_and_register_eps(missing_eps)
# Select and load a tool-capable model.
model = manager.catalog.get_model("qwen2.5-0.5b")
if model is None:
raise RuntimeError("Model 'qwen2.5-0.5b' was not found in the catalog.")
if not model.is_cached:
model.download(
lambda progress: print(
f"\rDownloading model: {progress:.2f}%", end="", flush=True
)
)
print()
model.load()
print("Model loaded and ready.")
try:
with ChatSession(model) as session:
session.set_options(
RequestOptions(
search=SearchOptions(temperature=0.0, max_output_tokens=512)
)
)
for tool in tools:
session.add_tool_definition(
tool["name"],
tool["description"],
json.dumps(tool["parameters"]),
)
system_prompt = (
"You are a helpful assistant with access to tools. "
"Use them when needed to answer questions accurately."
)
first_turn = True
print("\nTool-calling assistant ready! Type 'quit' to exit.\n")
while True:
user_input = input("You: ")
if user_input.strip().lower() in ("quit", "exit"):
break
with Request() as request:
if first_turn:
request.add_item(MessageItem.system(system_prompt))
first_turn = False
request.add_item(MessageItem.user(user_input))
with session.process_request(request) as response:
answer, pending_calls = response_content(response)
answer = process_tool_calls(session, answer, pending_calls)
print(f"Assistant: {answer}\n")
finally:
# Clean up
if model.is_loaded:
model.unload()
manager.close()
print("Model unloaded. Goodbye!")
当模型确定需要工具时,响应包含 tool_calls 而不是常规短信。 下一步演示如何检测和处理这些调用。
执行该工具并返回结果
在模型使用工具调用进行响应后,可以提取函数名称和参数,运行函数,并将结果发送回。
def process_tool_calls(session, answer, pending_calls):
"""Handle tool calls until the stateful session produces a final answer."""
while pending_calls:
with Request() as follow_up:
for call_id, function_name, arguments_json in pending_calls:
arguments = json.loads(arguments_json)
print(f" Tool call: {function_name}({arguments})")
result = tool_functions[function_name](**arguments)
follow_up.add_item(
ToolResultItem(call_id=call_id, result=json.dumps(result))
)
with session.process_request(follow_up) as next_response:
answer, pending_calls = response_content(next_response)
return answer
工具调用循环中的关键步骤包括:
-
检测工具调用 - 检查
response.choices[0].message.tool_calls。 - 执行函数 - 分析参数并调用本地函数。
-
返回结果 - 添加消息,其中包含角色
tool和匹配项tool_call_id。 - 获取最终答案 - 模型使用工具结果生成自然响应。
处理完整的工具调用循环
下面是将工具定义、SDK 初始化和工具调用循环合并到单个可运行文件中的完整应用程序。
创建一个名为 main.py 并添加以下完整代码的文件:
import json
from foundry_local_sdk import (
ChatSession,
Configuration,
FoundryLocalManager,
MessageItem,
Request,
RequestOptions,
SearchOptions,
TextItem,
ToolCallItem,
ToolResultItem,
)
# --- Tool definitions ---
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city or location",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit",
},
},
"required": ["location"],
},
},
{
"name": "calculate",
"description": "Perform a math calculation",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "The math expression to evaluate",
}
},
"required": ["expression"],
},
},
]
# --- Tool implementations ---
def get_weather(location, unit="celsius"):
"""Simulate a weather lookup."""
return {
"location": location,
"temperature": 22 if unit == "celsius" else 72,
"unit": unit,
"condition": "Sunny",
}
def calculate(expression):
"""Evaluate a math expression safely."""
allowed = set("0123456789+-*/(). ")
if not all(character in allowed for character in expression):
return {"error": "Invalid expression"}
try:
result = eval(expression, {"__builtins__": {}}, {})
return {"expression": expression, "result": result}
except Exception as error:
return {"error": str(error)}
tool_functions = {"get_weather": get_weather, "calculate": calculate}
def response_content(response):
text_parts = []
tool_calls = []
for item in response:
parts = item.parts if isinstance(item, MessageItem) else [item]
for part in parts:
if isinstance(part, TextItem):
text_parts.append(part.text)
elif isinstance(part, ToolCallItem):
tool_calls.append((part.call_id, part.name, part.arguments))
return "".join(text_parts), tool_calls
def process_tool_calls(session, answer, pending_calls):
"""Handle tool calls until the stateful session produces a final answer."""
while pending_calls:
with Request() as follow_up:
for call_id, function_name, arguments_json in pending_calls:
arguments = json.loads(arguments_json)
print(f" Tool call: {function_name}({arguments})")
result = tool_functions[function_name](**arguments)
follow_up.add_item(
ToolResultItem(call_id=call_id, result=json.dumps(result))
)
with session.process_request(follow_up) as next_response:
answer, pending_calls = response_content(next_response)
return answer
def main():
# Initialize the Foundry Local SDK
config = Configuration(app_name="foundry_local_samples")
FoundryLocalManager.initialize(config)
manager = FoundryLocalManager.instance
# Discover and register execution providers that are not already available.
missing_eps = [ep.name for ep in manager.discover_eps() if not ep.is_registered]
if missing_eps:
manager.download_and_register_eps(missing_eps)
# Select and load a tool-capable model.
model = manager.catalog.get_model("qwen2.5-0.5b")
if model is None:
raise RuntimeError("Model 'qwen2.5-0.5b' was not found in the catalog.")
if not model.is_cached:
model.download(
lambda progress: print(
f"\rDownloading model: {progress:.2f}%", end="", flush=True
)
)
print()
model.load()
print("Model loaded and ready.")
try:
with ChatSession(model) as session:
session.set_options(
RequestOptions(
search=SearchOptions(temperature=0.0, max_output_tokens=512)
)
)
for tool in tools:
session.add_tool_definition(
tool["name"],
tool["description"],
json.dumps(tool["parameters"]),
)
system_prompt = (
"You are a helpful assistant with access to tools. "
"Use them when needed to answer questions accurately."
)
first_turn = True
print("\nTool-calling assistant ready! Type 'quit' to exit.\n")
while True:
user_input = input("You: ")
if user_input.strip().lower() in ("quit", "exit"):
break
with Request() as request:
if first_turn:
request.add_item(MessageItem.system(system_prompt))
first_turn = False
request.add_item(MessageItem.user(user_input))
with session.process_request(request) as response:
answer, pending_calls = response_content(response)
answer = process_tool_calls(session, answer, pending_calls)
print(f"Assistant: {answer}\n")
finally:
# Clean up
if model.is_loaded:
model.unload()
manager.close()
print("Model unloaded. Goodbye!")
if __name__ == "__main__":
main()
运行工具调用助手:
python main.py
会看到类似于以下内容的输出:
Downloading model: 100.00%
Model loaded and ready.
Tool-calling assistant ready! Type 'quit' to exit.
You: What's the weather like today?
Tool call: get_weather({'location': 'current location'})
Assistant: The weather today is sunny with a temperature of 22°C.
You: What is 245 * 38?
Tool call: calculate({'expression': '245 * 38'})
Assistant: 245 multiplied by 38 equals 9,310.
You: quit
Model unloaded. Goodbye!
模型根据用户的消息决定何时调用工具。 对于天气问题,它调用 get_weather,对于数学问题,它调用 calculate,而对于常规问题,它直接响应,不需要调用任何工具。
示例存储库
本文的完整示例代码在 foundry-samples GitHub 存储库中提供。 若要克隆存储库并导航到示例,请使用:
git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/rust/foundry-local/tutorial-tool-calling
安装软件包
cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow
定义工具
工具调用允许模型请求代码运行函数并返回结果。 将可用工具定义为描述每个函数的名称、用途和参数的 JSON 架构列表。
添加
serde_json依赖项用于 JSON 的处理:cargo add serde_json打开
src/main.rs并添加以下工具定义:let weather_schema = json!({ "type": "object", "properties": { "location": {"type": "string", "description": "The city or location"}, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature unit" } }, "required": ["location"] }); let calculator_schema = json!({ "type": "object", "properties": { "expression": { "type": "string", "description": "The math expression to evaluate" } }, "required": ["expression"] });每个工具定义都包含一个
name、一个帮助模型决定何时使用它的description以及一个描述预期输入的parameters架构。添加实现每个工具的 Rust 函数:
let weather_schema = json!({ "type": "object", "properties": { "location": {"type": "string", "description": "The city or location"}, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature unit" } }, "required": ["location"] }); let calculator_schema = json!({ "type": "object", "properties": { "expression": { "type": "string", "description": "The math expression to evaluate" } }, "required": ["expression"] });模型不会直接运行这些函数。 它返回具有函数名称和参数的工具调用请求,代码执行该函数。
发送触发工具使用的消息
初始化 Foundry 本地 SDK,加载模型,并发送一条消息,通过调用工具使模型可以应答。
let manager = FoundryLocalManager::create(FoundryLocalConfig::new("foundry_local_samples"))?;
manager
.download_and_register_eps_with_progress(None, {
let mut current_ep = String::new();
move |ep_name: &str, percent: f64| {
if ep_name != current_ep {
if !current_ep.is_empty() {
println!();
}
current_ep = ep_name.to_string();
}
print!("\r {ep_name:<30} {percent:5.1}%");
io::stdout().flush().ok();
}
})
.await?;
println!();
let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
if !model.is_cached().await? {
println!("Downloading model...");
model
.download(Some(|progress: f64| {
print!("\r {progress:.1}%");
io::stdout().flush().ok();
}))
.await?;
println!();
}
model.load().await?;
let session = ChatSession::new(&model).await?;
session
.set_options(RequestOptions {
search: SearchOptions {
temperature: Some(0.7),
max_output_tokens: Some(512),
..Default::default()
},
tool_choice: Some(ToolChoice::Auto),
..Default::default()
})
.await?;
session
.add_tool_definition(
ToolDefinition::new("get_weather", weather_schema.to_string())
.with_description("Get the current weather for a location."),
)
.await?;
session
.add_tool_definition(
ToolDefinition::new("calculate", calculator_schema.to_string())
.with_description("Perform a math calculation."),
)
.await?;
当模型确定需要工具时,响应包含 tool_calls 而不是常规短信。 下一步演示如何检测和处理这些调用。
执行该工具并返回结果
在模型使用工具调用进行响应后,可以提取函数名称和参数,运行函数,并将结果发送回。
println!("\nTool-calling assistant ready! Type 'quit' to exit.\n");
let stdin = io::stdin();
loop {
print!("You: ");
io::stdout().flush()?;
let mut input = String::new();
stdin.lock().read_line(&mut input)?;
let input = input.trim();
if input.eq_ignore_ascii_case("quit") || input.eq_ignore_ascii_case("exit") {
break;
}
if input.is_empty() {
continue;
}
let mut items = Vec::new();
if session.turn_count() == 0 {
items.push(Item::system_message(vec![Item::text(
"You are a helpful assistant with access to tools. Use them when needed.",
)]));
}
items.push(Item::user_message(vec![Item::text(input)]));
loop {
let response = session
.process_request(Request::from_items(items).with_options(RequestOptions {
search: SearchOptions {
temperature: Some(0.7),
max_output_tokens: Some(512),
..Default::default()
},
tool_choice: Some(ToolChoice::Auto),
..Default::default()
}))
.await?;
let mut tool_results = Vec::new();
let mut answer = String::new();
for item in &response.items {
if let Some(call) = item.as_tool_call() {
let arguments: Value =
serde_json::from_str(&call.arguments).unwrap_or_else(|_| json!({}));
println!(" Tool call: {}({arguments})", call.name);
let result = execute_tool(&call.name, &arguments);
tool_results.push(Item::tool_result(call.call_id.clone(), result.to_string()));
} else if let Some(message) = item.as_message() {
answer.push_str(&message.text());
} else if let Some(text) = item.as_text() {
answer.push_str(text);
}
}
if tool_results.is_empty() {
println!("Assistant: {answer}\n");
break;
}
items = tool_results;
}
}
drop(session);
model.unload().await?;
println!("Model unloaded. Goodbye!");
工具调用循环中的关键步骤包括:
-
检测工具调用 - 检查
response.choices[0].message.tool_calls。 - 执行函数 - 分析参数并调用本地函数。
-
返回结果 - 添加包含角色
tool的消息和匹配工具调用 ID。 - 获取最终答案 - 模型使用工具结果生成自然响应。
处理完整的工具调用循环
下面是将工具定义、SDK 初始化和工具调用循环合并到单个可运行文件中的完整应用程序。
将 src/main.rs 的内容替换为完整的代码:
use foundry_local_sdk::{
ChatSession, FoundryLocalConfig, FoundryLocalManager, Item, Request, RequestOptions,
SearchOptions, ToolChoice, ToolDefinition,
};
use serde_json::{json, Value};
use std::io::{self, BufRead, Write};
fn execute_tool(name: &str, arguments: &Value) -> Value {
match name {
"get_weather" => {
let location = arguments["location"].as_str().unwrap_or("unknown");
let unit = arguments["unit"].as_str().unwrap_or("celsius");
let temp = if unit == "celsius" { 22 } else { 72 };
json!({
"location": location,
"temperature": temp,
"unit": unit,
"condition": "Sunny"
})
}
"calculate" => {
let expression = arguments["expression"].as_str().unwrap_or("");
let is_valid = expression
.chars()
.all(|character| "0123456789+-*/(). ".contains(character));
if !is_valid {
return json!({"error": "Invalid expression"});
}
match eval_expression(expression) {
Ok(result) => json!({"expression": expression, "result": result}),
Err(error) => json!({"error": error}),
}
}
_ => json!({"error": format!("Unknown function: {name}")}),
}
}
fn eval_expression(expr: &str) -> Result<f64, String> {
let expr = expr.replace(' ', "");
let chars: Vec<char> = expr.chars().collect();
let mut pos = 0;
let result = parse_add(&chars, &mut pos)?;
if pos < chars.len() {
return Err("Unexpected character".to_string());
}
Ok(result)
}
fn parse_add(chars: &[char], pos: &mut usize) -> Result<f64, String> {
let mut result = parse_mul(chars, pos)?;
while *pos < chars.len() && (chars[*pos] == '+' || chars[*pos] == '-') {
let op = chars[*pos];
*pos += 1;
let right = parse_mul(chars, pos)?;
result = if op == '+' {
result + right
} else {
result - right
};
}
Ok(result)
}
fn parse_mul(chars: &[char], pos: &mut usize) -> Result<f64, String> {
let mut result = parse_atom(chars, pos)?;
while *pos < chars.len() && (chars[*pos] == '*' || chars[*pos] == '/') {
let op = chars[*pos];
*pos += 1;
let right = parse_atom(chars, pos)?;
result = if op == '*' {
result * right
} else {
result / right
};
}
Ok(result)
}
fn parse_atom(chars: &[char], pos: &mut usize) -> Result<f64, String> {
if *pos < chars.len() && chars[*pos] == '(' {
*pos += 1;
let result = parse_add(chars, pos)?;
if *pos < chars.len() && chars[*pos] == ')' {
*pos += 1;
}
return Ok(result);
}
let start = *pos;
while *pos < chars.len() && (chars[*pos].is_ascii_digit() || chars[*pos] == '.') {
*pos += 1;
}
if start == *pos {
return Err("Expected number".to_string());
}
chars[start..*pos]
.iter()
.collect::<String>()
.parse::<f64>()
.map_err(|error| error.to_string())
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let weather_schema = json!({
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city or location"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit"
}
},
"required": ["location"]
});
let calculator_schema = json!({
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "The math expression to evaluate"
}
},
"required": ["expression"]
});
let manager = FoundryLocalManager::create(FoundryLocalConfig::new("foundry_local_samples"))?;
manager
.download_and_register_eps_with_progress(None, {
let mut current_ep = String::new();
move |ep_name: &str, percent: f64| {
if ep_name != current_ep {
if !current_ep.is_empty() {
println!();
}
current_ep = ep_name.to_string();
}
print!("\r {ep_name:<30} {percent:5.1}%");
io::stdout().flush().ok();
}
})
.await?;
println!();
let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
if !model.is_cached().await? {
println!("Downloading model...");
model
.download(Some(|progress: f64| {
print!("\r {progress:.1}%");
io::stdout().flush().ok();
}))
.await?;
println!();
}
model.load().await?;
let session = ChatSession::new(&model).await?;
session
.set_options(RequestOptions {
search: SearchOptions {
temperature: Some(0.7),
max_output_tokens: Some(512),
..Default::default()
},
tool_choice: Some(ToolChoice::Auto),
..Default::default()
})
.await?;
session
.add_tool_definition(
ToolDefinition::new("get_weather", weather_schema.to_string())
.with_description("Get the current weather for a location."),
)
.await?;
session
.add_tool_definition(
ToolDefinition::new("calculate", calculator_schema.to_string())
.with_description("Perform a math calculation."),
)
.await?;
println!("\nTool-calling assistant ready! Type 'quit' to exit.\n");
let stdin = io::stdin();
loop {
print!("You: ");
io::stdout().flush()?;
let mut input = String::new();
stdin.lock().read_line(&mut input)?;
let input = input.trim();
if input.eq_ignore_ascii_case("quit") || input.eq_ignore_ascii_case("exit") {
break;
}
if input.is_empty() {
continue;
}
let mut items = Vec::new();
if session.turn_count() == 0 {
items.push(Item::system_message(vec![Item::text(
"You are a helpful assistant with access to tools. Use them when needed.",
)]));
}
items.push(Item::user_message(vec![Item::text(input)]));
loop {
let response = session
.process_request(Request::from_items(items).with_options(RequestOptions {
search: SearchOptions {
temperature: Some(0.7),
max_output_tokens: Some(512),
..Default::default()
},
tool_choice: Some(ToolChoice::Auto),
..Default::default()
}))
.await?;
let mut tool_results = Vec::new();
let mut answer = String::new();
for item in &response.items {
if let Some(call) = item.as_tool_call() {
let arguments: Value =
serde_json::from_str(&call.arguments).unwrap_or_else(|_| json!({}));
println!(" Tool call: {}({arguments})", call.name);
let result = execute_tool(&call.name, &arguments);
tool_results.push(Item::tool_result(call.call_id.clone(), result.to_string()));
} else if let Some(message) = item.as_message() {
answer.push_str(&message.text());
} else if let Some(text) = item.as_text() {
answer.push_str(text);
}
}
if tool_results.is_empty() {
println!("Assistant: {answer}\n");
break;
}
items = tool_results;
}
}
drop(session);
model.unload().await?;
println!("Model unloaded. Goodbye!");
Ok(())
}
运行工具调用助手:
cargo run
会看到类似于以下内容的输出:
Downloading model: 100.00%
Model loaded and ready.
Tool-calling assistant ready! Type 'quit' to exit.
You: What's the weather like today?
Tool call: get_weather({"location":"current location"})
Assistant: The weather today is sunny with a temperature of 22°C.
You: What is 245 * 38?
Tool call: calculate({"expression":"245 * 38"})
Assistant: 245 multiplied by 38 equals 9,310.
You: quit
Model unloaded. Goodbye!
模型根据用户的消息决定何时调用工具。 对于天气问题,它调用 get_weather,对于数学问题,它调用 calculate,而对于常规问题,它直接响应,不需要调用任何工具。
示例存储库
克隆 Foundry 示例GitHub存储库并转到 C++ 示例:
git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/tutorial-tool-calling-assistant
安装软件包
C++ 示例需要:
配置并生成示例:
cmake -S . -B build
cmake --build build --config Release
在配置期间,示例将 Microsoft.AI.Foundry.Local.Runtime NuGet 包的 2.2.1 版本还原到 build/_packages。 该包包含用于 Windows、Linux 和 macOS 的 C++ 标头和本机库。 不需要单独的 WinML 包。
CMake 配置根据您的操作系统和体系结构选择运行时资源,并将所需的本机库复制到可执行文件旁边。 在 macOS 和 Linux 上,从 build中运行可执行文件。 在 Windows 上,运行位于 .exe 中的 build 文件。
定义工具
定义可用的工具和实现它们的本地函数:
constexpr const char* kTimeSchema = R"({
"type": "object",
"properties": {
"timezone": {"type": "string", "description": "Requested timezone label"}
},
"required": ["timezone"]
})";
std::string GetLocalTime() {
const auto now = std::chrono::system_clock::to_time_t(std::chrono::system_clock::now());
std::tm local_time{};
#ifdef _WIN32
localtime_s(&local_time, &now);
#else
localtime_r(&now, &local_time);
#endif
std::ostringstream output;
output << std::put_time(&local_time, "%Y-%m-%d %H:%M:%S");
return R"({"timezone":"local","time":")" + output.str() + R"("})";
}
发送触发工具使用的消息
初始化 SDK,加载模型,并发送可以使用工具的请求:
Configuration config("foundry_local_cpp_tool_assistant");
Manager manager(std::move(config));
auto model = manager.GetCatalog().GetModel("qwen2.5-0.5b");
if (!model) {
throw std::runtime_error("Model 'qwen2.5-0.5b' was not found in the catalog.");
}
if (!model->IsCached()) {
model->Download([](float progress) {
std::cout << "\rDownloading model: " << static_cast<int>(progress) << "%" << std::flush;
return 0;
});
std::cout << "\n";
}
model->Load();
执行该工具并返回结果
检测工具调用,执行本地函数,返回其结果,并请求模型获取最终答案:
Request request{
SystemMessage("Use the available tool when current time is requested."),
UserMessage("What time is it?"),
};
request.SetOptions({
.search = {.temperature = 0.0F, .max_output_tokens = 256, .seed = 42},
.tool_choice = FOUNDRY_LOCAL_TOOL_CHOICE_REQUIRED,
});
Response response = session.ProcessRequest(request);
for (int iteration = 0; iteration < 8; ++iteration) {
bool called_tool = false;
for (const Item& item : response.GetItems()) {
if (item.GetType() == FOUNDRY_LOCAL_ITEM_MESSAGE) {
std::cout << "Assistant: ";
PrintAssistant(item);
continue;
}
if (item.GetType() != FOUNDRY_LOCAL_ITEM_TOOL_CALL) {
continue;
}
const auto call = item.GetToolCall();
if (call.name != "get_current_time") {
throw std::runtime_error("The model requested an unknown tool.");
}
Request tool_result;
tool_result.AddItem(Item::ToolResult(std::string(call.call_id), GetLocalTime()));
tool_result.SetOptions({
.search = {.temperature = 0.0F, .max_output_tokens = 256, .seed = 42},
.tool_choice = FOUNDRY_LOCAL_TOOL_CHOICE_NONE,
});
response = session.ProcessRequest(tool_result);
called_tool = true;
break;
}
if (!called_tool) {
break;
}
}
完整代码
#include <foundry_local/foundry_local_cpp.h>
#include <chrono>
#include <ctime>
#include <iomanip>
#include <iostream>
#include <sstream>
#include <string>
using namespace foundry_local;
constexpr const char* kTimeSchema = R"({
"type": "object",
"properties": {
"timezone": {"type": "string", "description": "Requested timezone label"}
},
"required": ["timezone"]
})";
std::string GetLocalTime() {
const auto now = std::chrono::system_clock::to_time_t(std::chrono::system_clock::now());
std::tm local_time{};
#ifdef _WIN32
localtime_s(&local_time, &now);
#else
localtime_r(&now, &local_time);
#endif
std::ostringstream output;
output << std::put_time(&local_time, "%Y-%m-%d %H:%M:%S");
return R"({"timezone":"local","time":")" + output.str() + R"("})";
}
void PrintAssistant(const Item& message) {
for (const Item& part : message.GetMessage().parts) {
if (part.GetType() == FOUNDRY_LOCAL_ITEM_TEXT) {
std::cout << part.GetText().text;
}
}
std::cout << "\n";
}
int main() {
try {
Configuration config("foundry_local_cpp_tool_assistant");
Manager manager(std::move(config));
auto model = manager.GetCatalog().GetModel("qwen2.5-0.5b");
if (!model) {
throw std::runtime_error("Model 'qwen2.5-0.5b' was not found in the catalog.");
}
if (!model->IsCached()) {
model->Download([](float progress) {
std::cout << "\rDownloading model: " << static_cast<int>(progress) << "%" << std::flush;
return 0;
});
std::cout << "\n";
}
model->Load();
{
ChatSession session(*model);
session.AddToolDefinition(ToolDefinition{
"get_current_time",
"Get the current local date and time.",
kTimeSchema,
});
Request request{
SystemMessage("Use the available tool when current time is requested."),
UserMessage("What time is it?"),
};
request.SetOptions({
.search = {.temperature = 0.0F, .max_output_tokens = 256, .seed = 42},
.tool_choice = FOUNDRY_LOCAL_TOOL_CHOICE_REQUIRED,
});
Response response = session.ProcessRequest(request);
for (int iteration = 0; iteration < 8; ++iteration) {
bool called_tool = false;
for (const Item& item : response.GetItems()) {
if (item.GetType() == FOUNDRY_LOCAL_ITEM_MESSAGE) {
std::cout << "Assistant: ";
PrintAssistant(item);
continue;
}
if (item.GetType() != FOUNDRY_LOCAL_ITEM_TOOL_CALL) {
continue;
}
const auto call = item.GetToolCall();
if (call.name != "get_current_time") {
throw std::runtime_error("The model requested an unknown tool.");
}
Request tool_result;
tool_result.AddItem(Item::ToolResult(std::string(call.call_id), GetLocalTime()));
tool_result.SetOptions({
.search = {.temperature = 0.0F, .max_output_tokens = 256, .seed = 42},
.tool_choice = FOUNDRY_LOCAL_TOOL_CHOICE_NONE,
});
response = session.ProcessRequest(tool_result);
called_tool = true;
break;
}
if (!called_tool) {
break;
}
}
}
model->Unload();
manager.Shutdown();
} catch (const Error& error) {
std::cerr << "Foundry Local error [" << error.Code() << "]: " << error.what() << "\n";
return 1;
} catch (const std::exception& error) {
std::cerr << "Error: " << error.what() << "\n";
return 1;
}
return 0;
}
运行助手:
./build/tutorial-tool-calling-assistant
清理资源
卸载模型后,模型权重将保留在本地缓存中。 这意味着下次运行应用程序时,将跳过下载步骤,模型加载速度更快。 除非需要回收磁盘空间,否则不需要进行额外的清理。