工具

您可以注册工具(也称为函数)，LLM在构建答案时可能会决定调用这些工具。参见OpenAI函数、Ollama工具或Anthropic工具使用。

并非所有LLM模型都支持工具功能，在这些情况下，GenAIScript也支持通过系统提示实现工具调用的回退机制（参见Fallback Tools）。

`defTool`

defTool 用于定义一个可供大语言模型调用的工具。它接收一个JSON模式来定义输入，并期望输出字符串。参数使用parameters schema进行定义。

LLM决定自行调用此工具！

defTool(
    "current_weather",
    "get the current weather",
    {
        city: "",
    },
    (args) => {
        const { location } = args
        if (location === "Brussels") return "sunny"
        else return "variable"
    }
)

在上面的示例中，我们定义了一个名为current_weather的工具，它接收位置作为输入并返回天气信息。

天气工具示例

这个例子使用current_weather工具来获取布鲁塞尔的天气。

script({
    model: "small",
    title: "Weather as function",
    description:
        "Query the weather for each city using a dummy weather function",
    temperature: 0.5,
    files: "src/cities.md",
    tests: {
        files: "src/cities.md",
        keywords: "Brussels",
    },
})

$`Query the weather for each listed city and return the results as a table.`

def("CITIES", env.files)

defTool(
    "get_current_weather",
    "get the current weather",
    {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA",
            },
        },
        required: ["location"],
    },
    (args) => {
        const { context, location } = args
        const { trace } = context

        trace.log(`Getting weather for ${location}...`)

        let content = "variable"
        if (location === "Brussels") content = "sunny"

        return content
    }
)

数学工具示例

这个示例使用数学表达式求值器来评估一个数学表达式。

script({
    title: "math-agent",
    model: "small",
    description: "A port of https://ts.llamaindex.ai/examples/agent",
    parameters: {
        question: {
            type: "string",
            default: "How much is 11 + 4? then divide by 3?",
        },
    },
    tests: {
        description: "Testing the default prompt",
        keywords: "5",
    },
})

defTool(
    "sum",
    "Use this function to sum two numbers",
    { a: 1, b: 2 },
    ({ a, b }) => {
        console.log(`${a} + ${b}`)
        return `${a + b}`
    }
)

defTool(
    "divide",
    "Use this function to divide two numbers",
    {
        type: "object",
        properties: {
            a: {
                type: "number",
                description: "The first number",
            },
            b: {
                type: "number",
                description: "The second number",
            },
        },
        required: ["a", "b"],
    },
    ({ a, b }) => {
        console.log(`${a} / ${b}`)
        return `${a / b}`
    }
)

$`Answer the following arithmetic question:

    ${env.vars.question}
`

在系统脚本中复用工具

您可以在系统脚本中定义工具，并将它们像其他系统脚本或工具一样包含到您的主脚本中。

system({ description: "Random tools" })

export default function (ctx: ChatGenerationContext) {
    const { defTool } = ctx
    defTool("random", "Generate a random number", {}, () => Math.random())
}

确保在系统脚本中使用system而不是script。

script({
    title: "Random number",
    tools: ["random"],
})
$`Generate a random number.

同一系统脚本的多个实例

您可以在脚本中多次包含相同的系统脚本，只需使用不同的参数即可。

script({
    system: [
        "system.agent_git", // git operations on current repository
        {
            id: "system.agent_git", // same system script
            parameters: { repo: "microsoft/genaiscript" } // but with new parameters
            variant: "genaiscript" // appened to the identifier to keep tool identifiers unique
        }
    ]
})

模型上下文协议工具

Model Context Provider (MCP) 是一个开放协议，可实现LLM应用程序与外部数据源和工具之间的无缝集成。

您可以利用MCP服务器为您的LLM提供工具。

defTool({
    memory: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-memory"],
    },
})

更多信息请参见Model Context Protocol Tools。

代理工具

Agentic 是一个标准化的AI函数/工具库，专为常规TS使用和基于LLM的使用场景进行了优化。您可以在脚本中使用defTool来注册任何agentic工具。

import { calculator } from "@agentic/calculator"
defTool(calculator)

查看Agentic tools获取更多信息。

回退工具支持

部分LLM模型没有内置工具支持。对于这些模型，可以通过系统提示启用工具支持。性能可能低于内置工具，但仍然可以使用工具功能。

工具支持是通过system.tool_calls实现的，它会"教导"大语言模型如何调用工具。当启用此模式时，您将看到大语言模型返回的工具调用令牌。

GenAIScript维护了一个不支持工具的知名模型列表，因此对于这些模型会自动处理。

要启用此模式，您可以

在脚本中添加fallbackTools选项

script({
    fallbackTools: true,
})

或者在CLI中添加--fallack-tools标志

npx genaiscript run ... --fallback-tools

打包为系统脚本

要选择哪些工具包含在脚本中，您可以将它们分组到系统脚本中。例如，current_weather工具可以包含在system.current_weather.genai.mjs脚本中。

script({
    title: "Get the current weather",
})
defTool("current_weather", ...)

然后在tools字段中使用工具ID。

script({
    ...,
    tools: ["current_weather"],
})

示例

让我们通过一个问答脚本来说明工具如何协同工作。

在下面的脚本中，我们添加了retrieval_web_search工具。这个工具会在需要时调用retrieval.webSearch。

script({
    title: "Answer questions",
    tool: ["retrieval_web_search"]
})

def("FILES", env.files)

$`Answer the questions in FILES using a web search.

- List a summary of the answers and the sources used to create the answers.

然后我们可以将这个脚本应用到下面的questions.md文件。

- What is the weather in Seattle?
- What laws were voted in the USA congress last week?

在第一个请求之后，LLM会要求为每个问题调用web_search。网络搜索结果随后会被添加到LLM的消息历史中，并再次发出请求。第二次请求会产生包含网络搜索结果的最终结果。

内置工具

fs_ask_file 对文件内容运行LLM查询。使用此工具从文件中提取信息。

fs_data_query 使用GROQ语法查询文件中的数据

fs_diff_files 计算两个不同文件之间的差异。要比较文件的不同版本，请使用git diff命令。

fs_find_files 查找匹配通配符模式的文件。使用pattern参数指定在文件内容中搜索的正则表达式。注意不要请求过多文件。

fs_read_file 从文件系统中以文本形式读取文件。如果文件不存在则返回undefined。

git_branch_default 使用客户端获取默认分支。

git_branch_current 使用客户端获取当前分支。

git_branch_list 使用客户端列出所有分支。

git_list_commits 使用git log命令生成提交历史记录。

git_status 使用客户端生成仓库状态。

git_last_tag 使用客户端获取最新的标签。

git_diff 使用git diff命令计算文件差异。如果差异过大，则返回已修改/添加的文件列表。

github_actions_workflows_list 列出所有github工作流。

github_actions_jobs_list 列出GitHub工作流运行的所有任务。

github_actions_job_logs_get 下载GitHub工作流任务日志。如果日志过大，可使用'github_actions_job_logs_diff'来比较日志。

github_actions_job_logs_diff 对比两个GitHub工作流任务日志。

github_files_get 从代码仓库获取文件。

github_files_list 列出仓库中的所有文件。

github_issues_list 列出仓库中的所有问题。

github_issues_get 通过编号获取单个问题。

github_issues_comments_list 获取某个issue的评论。

github_pulls_list 列出仓库中的所有拉取请求。

github_pulls_get 通过编号获取单个拉取请求。

github_pulls_review_comments_list 获取拉取请求的审阅评论。

math_eval 评估数学表达式。不要尝试自行计算算术运算，请使用此工具。

md_find_files 获取文档markdown/MDX文件的目录结构。返回每个匹配项的文件名、标题和描述。使用pattern参数指定在文件内容中搜索的正则表达式。

md_read_frontmatter 读取markdown或MDX文件的前置元数据。

meta_prompt 该工具将OpenAI的元提示指南应用于用户提示。修改自https://platform.openai.com/docs/guides/prompt-generation?context=text-out。

meta_schema 为描述的JSON生成有效的JSON模式。来源 https://platform.openai.com/docs/guides/prompt-generation?context=structured-output-schema。

node_test 使用`npm test`构建并测试当前项目

python_code_interpreter_run 在Docker容器中执行用于数据分析任务的Python 3.12代码。返回处理输出结果。不要生成可视化图表。可用的软件包仅限于numpy===2.1.3、pandas===2.2.3、scipy===1.14.1、matplotlib===3.9.2。没有网络连接。不要尝试安装其他软件包或发起网络请求。由于Python代码在独立容器中运行，您必须复制所有必要文件或传递所有数据。

python_code_interpreter_copy_files_to_container 将文件从工作区文件系统复制到容器文件系统。不要使用绝对路径。返回每个文件在python容器中的复制路径。

python_code_interpreter_read_file 从容器文件系统中读取文件。不支持绝对路径。

retrieval_fuzz_search 通过文件全文和模糊距离搜索关键词。

retrieval_vector_search 使用嵌入向量和相似度距离搜索文件。

retrieval_web_search 使用Tavily或Bing搜索为用户查询进行网络搜索。

think 使用该工具来思考某事。它不会获取新信息或更改数据库，只是将想法追加到日志中。当需要复杂推理或某些缓存记忆时使用它。

transcribe 使用语音转文本模型从音频/视频文件生成文字记录。

user_input_confirm 向用户请求确认消息。

user_input_select 让用户选择一个选项。

user_input_text 要求用户输入文本。

video_probe 探测视频文件并返回元数据信息

video_extract_audio 从视频文件中提取音频到音频文件。返回音频文件名。

video_extract_clip 从视频文件中提取片段。返回视频文件名。

video_extract_frames 从视频文件中提取帧

vision_ask_images 使用视觉模型对多张图像运行查询