作者：来自 Elastic Carly Richmond

你是否经常听到 AI 代理（AI agents）这个词，但不太确定它们是什么，或者如何在 TypeScript（或 JavaScript）中构建一个？跟我一起深入了解 AI 代理的概念、它们的可能应用场景，以及一个使用 AI SDK 和 Elasticsearch 构建的旅行规划代理示例。

你是否经常听到 AI 代理这个词，但不太确定它们是什么，或者它们如何与 Elastic 关联？在这里，我将深入探讨 AI 代理，具体包括：

• 什么是 AI 代理？

• AI 代理可以解决哪些问题？

• 一个基于 AI SDK、TypeScript 和 Elasticsearch 的旅行规划代理示例，代码可在 GitHub 上找到。

什么是 AI 代理？

AI 代理是一种能够自主执行任务并代表人类采取行动的软件，它利用人工智能实现这一目标。AI 代理通过结合一个或多个大语言模型（large language models - LLMs）与用户定义的工具（或函数）来执行特定操作。例如，这些工具可以执行以下操作：

• 从数据库、传感器、API 或 Elasticsearch 等搜索引擎提取信息。

• 执行复杂计算，并让 LLM 总结其结果。

• 基于各种数据输入快速做出关键决策。

• 根据响应触发必要的警报和反馈。

AI 代理可以做什么？

AI 代理可以根据其类型在多个领域中应用，可能的示例包括：

• 基于效用的代理：评估行动并提供推荐以最大化收益，例如根据用户的观看历史推荐电影和电视剧。

• 基于模型的代理：根据传感器输入实时决策，例如自动驾驶汽车或智能吸尘器。

• 学习型代理：结合数据和机器学习识别模式和异常，例如用于欺诈检测。

• 投资建议代理：根据用户的风险偏好和现有投资组合提供投资建议，以最大化收益。如果能权衡准确性、声誉风险和监管因素，这将加速决策过程。

• 简单聊天机器人：如当前的聊天机器人，可访问用户账户信息并用自然语言回答基本问题。

示例：旅行规划助手

为了更好地理解 AI 代理的功能，以及如何使用熟悉的 Web 技术构建一个 AI 代理，我们来看一个使用 AI SDK、TypeScript 和 Elasticsearch 编写的简单旅行规划助手示例。

架构

我们的示例由 5 个不同的元素组成：

1. 一个名为 weatherTool 的工具，从 Weather API 获取提问者指定位置的天气数据。

2. 一个名为 fcdoTool 的工具，从 GOV.UK content API 提供目的地的当前旅行状态。

3. flightTool 工具使用简单查询从 Elasticsearch 获取航班信息。

4. 以上所有信息都会传递给 LLM GPT-4 Turbo。

模型选择

在构建你的第一个 AI 代理时，确定使用哪个模型可能会很困难。资源如 Hugging Face Open LLM Leaderboard 是一个不错的起点。此外，你还可以参考 Berkeley Function-Calling Leaderboard 来获取工具使用的指导。

在我们的案例中，AI SDK 特别推荐使用具有强大工具调用能力的模型，例如 gpt-4 或 gpt-4-turbo，这在其 Prompt Engineering 文档中有详细说明。如果选择了错误的模型，可能会导致 LLM 无法按预期调用多个工具，甚至会出现兼容性错误，如下所示：

# Llama3 lack of tooling support (3.1 or higher)
llama3 does not support tools# Unsupported toolChoice option to configure tool usage
AI_UnsupportedFunctionalityError: 'Unsupported tool choice type: required' functionality not supported.

先决条件

要运行此示例，请确保按照仓库 README 中的先决条件进行操作。

基础聊天助手

你可以使用 AI SDK 创建的最简单的 AI 代理将生成来自 LLM 的响应，而无需任何额外的上下文。AI SDK 支持许多 JavaScript 框架，具体可参考其文档。然而，AI SDK UI 库文档列出了对 React、Svelte、Vue.js 和 SolidJS 的不同支持，许多教程针对 Next.js。因此，我们的示例使用 Next.js 编写。

任何 AI SDK 聊天机器人的基本结构使用 useChat 钩子来处理来自后端路由的请求，默认情况下是 /api/chat/：

page.tsx 文件包含了我们在 Chat 组件中的客户端实现，包括由 useChat hook 暴露的提交、加载和错误处理功能。加载和错误处理功能是可选的，但建议提供请求状态的指示。与简单的 REST 调用相比，代理可能需要相当长的时间来响应，因此在此过程中保持用户更新状态非常重要，避免用户快速连续点击和重复调用。

由于该组件涉及客户端交互，我使用了 use client 指令，以确保该组件被视为客户端包的一部分：

'use client';import { useChat } from '@ai-sdk/react';
import Spinner from './components/spinner';export default function Chat() {/* useChat hook helps us handle the input, resulting messages, and also handle the loading and error states for a better user experience */const { messages, input, handleInputChange, handleSubmit, isLoading, stop, error, reload } = useChat();return (<div className="chat__form"><div className="chat__messages">{/* Display all user messages and assistant responses */messages.map(m => (<div key={m.id} className="message"><div>{ /* Messages with the role of *assistant* denote responses from the LLM*/ }<div className="role">{m.role === "assistant" ? "Sorley" : "Me"}</div>{ /* User or LLM generated content */}<div className="itinerary__div" dangerouslySetInnerHTML={{ __html: markdownConverter.makeHtml(m.content) }}></div></div></div>))}</div>{/* Spinner shows when awaiting a response */isLoading && (<div className="spinner__container"><Spinner /><button id="stop__button" type="button" onClick={() => stop()}>Stop</button></div>)}{/* Show error message and return button when something goes wrong */error && (<><div className="error__container">Unable to generate a plan. Please try again later!</div><button id="retry__button" type="button" onClick={() => reload()}>Retry</button></>)}{ /* Form using default input and submission handler form the useChat hook */ }<form onSubmit={handleSubmit}><inputclassName="search-box__input"value={input}placeholder="Where would you like to go?"onChange={handleInputChange}disabled={error != null}/></form></div>);
}

Chat 组件将通过钩子暴露的 input 属性保持用户输入，并在提交时将响应发送到相应的路由。我使用了默认的 handleSubmit 方法，它将调用 /ai/chat/ 的 POST 路由。

该路由的处理程序位于 /ai/chat/route.ts 中，通过 OpenAI provider 程序初始化与 gpt-4-turbo LLM 的连接：

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { NextResponse } from 'next/server';// Allow streaming responses up to 30 seconds to address typically longer responses from LLMs
export const maxDuration = 30;// Post request handler
export async function POST(req: Request) {const { messages } = await req.json();try {// Generate response from the LLM using the provided model, system prompt and messagesconst result = streamText({model: openai('gpt-4-turbo'),system: 'You are a helpful assistant that returns travel itineraries',messages});// Return data stream to allow the useChat hook to handle the results as they are streamed through for a better user experiencereturn result.toDataStreamResponse();} catch(e) {console.error(e);return new NextResponse("Unable to generate a plan. Please try again later!");}
}

请注意，上述实现将默认从环境变量 OPENAI_API_KEY 中提取 API 密钥。如果需要自定义 OpenAI 提供程序的配置，可以使用 createOpenAI 方法来覆盖提供程序的设置。

通过以上路由，结合 Showdown 帮助将 GPT 的 Markdown 输出格式化为 HTML，再加上一些 CSS 魔法（在 globals.css 文件中），我们最终得到了一个简单的响应式 UI，可以根据用户的提示生成行程：

添加工具

向 AI 代理添加工具基本上就是创建 LLM 可以使用的自定义功能，以增强其生成的响应。在此阶段，我将添加 3 个新的工具，LLM 可以选择在生成行程时使用，如下图所示：

天气工具

虽然生成的行程是一个很好的开始，但我们可能希望添加 LLM 没有经过训练的额外信息，比如天气。这促使我们编写第一个工具，它不仅可以作为 LLM 的输入，还能提供额外的数据，帮助我们调整 UI。

创建的天气工具，完整代码如下，接受一个参数 location，LLM 将从用户输入中提取该位置。schema 属性使用 TypeScript 的 schema 验证库 Zod 来验证传入的参数类型，确保传递的是正确的参数类型。description 属性允许你定义工具的功能，帮助 LLM 决定是否调用该工具。

import { tool as createTool } from 'ai';
import { z } from 'zod';import { WeatherResponse } from '../model/weather.model';export const weatherTool = createTool({description: 'Display the weather for a holiday location',parameters: z.object({location: z.string().describe('The location to get the weather for')}),execute: async function ({ location }) {// While a historical forecast may be better, this example gets the next 3 daysconst url = `https://api.weatherapi.com/v1/forecast.json?q=${location}&days=3&key=${process.env.WEATHER_API_KEY}`;try {const response = await fetch(url);const weather : WeatherResponse = await response.json();return { location: location, condition: weather.current.condition.text, condition_image: weather.current.condition.icon,temperature: Math.round(weather.current.temp_c),feels_like_temperature: Math.round(weather.current.feelslike_c),humidity: weather.current.humidity};} catch(e) {console.error(e);return { message: 'Unable to obtain weather information', location: location};}}
});

你可能已经猜到，execute 属性是我们定义异步函数并实现工具逻辑的地方。具体来说，发送到天气 API 的位置会传递给我们的工具函数。然后，响应会被转换为一个单一的 JSON 对象，可以显示在 UI 上，并且也用于生成行程。

鉴于我们目前只运行一个工具，因此不需要考虑顺序或并行流程。简单来说，就是在原始 api/chat 路由中处理 LLM 输出的 streamText 方法中添加 tools 属性：

import { weatherTool } from '@/app/ai/weather.tool';// Other imports omittedexport const tools = {displayWeather: weatherTool,
};// Post request handler
export async function POST(req: Request) {const { messages } = await req.json();// Generate response from the LLM using the provided model, system prompt and messages (try catch block omitted)const result = streamText({model: openai('gpt-4-turbo'),system: 'You are a helpful assistant that returns travel itineraries based on the specified location.',messages,maxSteps: 2,tools});// Return data stream to allow the useChat hook to handle the results as they are streamed through for a better user experiencereturn result.toDataStreamResponse();
}

工具输出与消息一起提供，这使我们能够为用户提供更完整的体验。每条消息包含一个 parts 属性，其中包含 type 和 state 属性。当这些属性的值分别为 tool-invocation 和 result 时，我们可以从 toolInvocation 属性中提取返回的结果，并按需要显示它们。

更改后的 page.tsx 源代码将显示天气摘要以及生成的行程：

'use client';import { useChat } from '@ai-sdk/react';
import Image from 'next/image';import { Weather } from './components/weather';import pending from '../../public/multi-cloud.svg';export default function Chat() {/* useChat hook helps us handle the input, resulting messages, and also handle the loading and error states for a better user experience */const { messages, input, handleInputChange, handleSubmit, isLoading, stop, error, reload } = useChat();return (<div className="chat__form"><div className="chat__messages">{/* Display all user messages and assistant responses */messages.map(m => (<div key={m.id} className="message"><div>{ /* Messages with the role of *assistant* denote responses from the LLM */}<div className="role">{m.role === "assistant" ? "Sorley" : "Me"}</div>{ /* Tool handling */}<div className="tools__summary">{m.parts.map(part => {if (part.type === 'tool-invocation') {const { toolName, toolCallId, state } = part.toolInvocation;if (state === 'result') {{ /* Show weather results */}if (toolName === 'displayWeather') {const { result } = part.toolInvocation;return (<div key={toolCallId}><Weather {...result} /></div>);}} else {return (<div key={toolCallId}>{toolName === 'displayWeather' ? (<div className="weather__tool"><Image src={pending} width={80} height={80} alt="Placeholder Weather"/><p className="loading__weather__message">Loading weather...</p></div>) : null}</div>);}}})}</div>{ /* User or LLM generated content */}<div className="itinerary__div" dangerouslySetInnerHTML={{ __html: markdownConverter.makeHtml(m.content) }}></div></div></div>))}</div>{ /* Spinner and loading handling omitted */ }{ /* Form using default input and submission handler form the useChat hook */}<form onSubmit={handleSubmit}><inputclassName="search-box__input"value={input}placeholder="Where would you like to go?"onChange={handleInputChange}disabled={error != null}/></form></div>);
}

上述代码将向用户提供以下输出：

FCO 工具

AI 代理的强大之处在于 LLM 可以选择触发多个工具来获取相关信息，以生成响应。假设我们想要查看目标国家的旅行指南。下面的代码展示了如何创建一个新的工具 fcdoGuidance，它可以触发一个对 GOV.UK Content API 的 API 调用：

import { tool as createTool } from 'ai';
import { z } from 'zod';import { FCDOResponse } from '../model/fco.model';export const fcdoTool = createTool({description: 'Display the FCDO guidance for a destination',parameters: z.object({country: z.string().describe('The country of the location to get the guidance for')}),execute: async function ({ country }) {const url = `https://www.gov.uk/api/content/foreign-travel-advice/${country.toLowerCase()}`;try {const response = await fetch(url, { headers: { 'Content-Type': 'application/json' } });const fcoResponse: FCDOResponse = await response.json();const alertStatus: string = fcoResponse.details.alert_status.length == 0 ? 'Unknown' : fcoResponse.details.alert_status[0].replaceAll('_', ' ');return { status: alertStatus, url: fcoResponse.details?.document?.url};} catch(e) {console.error(e);return { message: 'Unable to obtain FCDO information', location: location};}}
});

你会注意到，格式与之前讨论的天气工具非常相似。事实上，要将该工具包含到 LLM 输出中，只需将其添加到 tools 属性，并修改 /api/chat 路由中的提示即可：

// Imports omittedexport const tools = {fcdoGuidance: fcdoTool,displayWeather: weatherTool,
};// Post request handler
export async function POST(req: Request) {const { messages } = await req.json();// Generate response from the LLM using the provided model, system prompt and messages (try/ catch block omitted)const result = streamText({model: openai('gpt-4-turbo'),system:"You are a helpful assistant that returns travel itineraries based on a location" + "Use the current weather from the displayWeather tool to adjust the itinerary and give packing suggestions." +"If the FCDO tool warns against travel DO NOT generate an itinerary.",messages,maxSteps: 2,tools});// Return data stream to allow the useChat hook to handle the results as they are streamed through for a better user experiencereturn result.toDataStreamResponse();
}

一旦将显示工具输出的组件添加到页面，对于不建议旅行的国家，输出应该如下所示：

支持工具调用的LLM可以选择是否调用工具，除非它认为有必要。使用gpt-4-turbo时，我们的两个工具会并行调用。然而，之前尝试使用llama3.1时，取决于输入，只有一个模型会被调用。

航班信息工具

RAG（Retrieval Augmented Generation - 检索增强生成）指的是一种软件架构，其中从搜索引擎或数据库中提取的文档作为上下文传递给 LLM，以基于提供的文档集来生成回应。这种架构允许 LLM 根据它之前没有训练过的数据生成更准确的回应。虽然 Agentic RAG 通过定义的工具或结合向量或混合搜索处理文档，但也可以像我们这里所做的那样，利用 RAG 作为与传统词汇搜索的复杂流程的一部分。

为了将航班信息与其他工具一起传递给LLM，最后一个工具 flightTool 通过 Elasticsearch JavaScript 客户端，从 Elasticsearch 中拉取出发和到达航班的航班信息，使用提供的出发地和目的地：

import { tool as createTool } from 'ai';
import { z } from 'zod';import { Client } from '@elastic/elasticsearch';
import { SearchResponseBody } from '@elastic/elasticsearch/lib/api/types';import { Flight } from '../model/flight.model';const index: string = "upcoming-flight-data";
const client: Client = new Client({node: process.env.ELASTIC_ENDPOINT,auth: {apiKey: process.env.ELASTIC_API_KEY || "",},
});function extractFlights(response: SearchResponseBody<Flight>): (Flight | undefined)[] {return response.hits.hits.map(hit => { return hit._source})
}export const flightTool = createTool({description:"Get flight information for a given destination from Elasticsearch, both outbound and return journeys",parameters: z.object({destination: z.string().describe("The destination we are flying to"),origin: z.string().describe("The origin we are flying from (defaults to London if not specified)"),}),execute: async function ({ destination, origin }) {try {const responses = await client.msearch({searches: [{ index: index },{query: {bool: {must: [{match: {origin: origin,},},{match: {destination: destination,},},],},},},// Return leg{ index: index },{query: {bool: {must: [{match: {origin: destination,},},{match: {destination: origin,},},],},},},],});if (responses.responses.length < 2) {throw new Error("Unable to obtain flight data");}return {outbound: extractFlights(responses.responses[0] as SearchResponseBody<Flight>),inbound: extractFlights(responses.responses[1] as SearchResponseBody<Flight>)};} catch (e) {console.error(e);return {message: "Unable to obtain flight information",location: location,};}},
});

这个示例使用了 Multi search API 来分别拉取出发和到达航班的信息，然后通过 extractFlights 工具方法提取文档。

为了使用工具的输出，我们需要再次修改我们的提示和工具集合，更新 /ai/chat/route.ts 文件：

// Imports omitted// Allow streaming responses up to 30 seconds to address typically longer responses from LLMs
export const maxDuration = 30;export const tools = {getFlights: flightTool,displayWeather: weatherTool,fcdoGuidance: fcdoTool
};// Post request handler
export async function POST(req: Request) {const { messages } = await req.json();// Generate response from the LLM using the provided model, system prompt and messages (try/ catch block omitted)const result = streamText({model: openai('gpt-4-turbo'),system:"You are a helpful assistant that returns travel itineraries based on location, the FCDO guidance from the specified tool, and the weather captured from the displayWeather tool." + "Use the flight information from tool getFlights only to recommend possible flights in the itinerary." + "Return an itinerary of sites to see and things to do based on the weather." + "If the FCDO tool warns against travel DO NOT generate an itinerary.",messages,maxSteps: 2,tools});// Return data stream to allow the useChat hook to handle the results as they are streamed through for a better user experiencereturn result.toDataStreamResponse();
}

通过最终的提示，所有 3 个工具将被调用，以生成包含航班选项的行程：

总结

如果你之前对 AI 代理还不完全了解，现在你应该清楚了！我们通过使用 AI SDK、Typescript 和 Elasticsearch 的简单旅行规划示例来进行了解。我们可以扩展我们的规划器，添加其他数据源，允许用户预订旅行以及旅游，甚至根据位置生成图像横幅（目前 AI SDK 中对此的支持仍处于实验阶段）。

如果你还没有深入了解代码，可以在这里查看！

资源

1. AI SDK 核心文档
2. AI SDK 核心 > 工具调用
3. Elasticsearch JavaScript 客户端
4. 旅行规划 AI 代理 | GitHub

想要获得 Elastic 认证吗？查看下次 Elasticsearch 工程师培训的时间！

Elasticsearch 拥有众多新功能，可以帮助你为你的使用案例构建最佳搜索解决方案。深入了解我们的示例笔记本，了解更多内容，开始免费云试用，或在本地机器上尝试 Elastic。

原文：Building AI Agents with AI SDK and Elastic - Elasticsearch Labs