【转载】AI 智能体（AI Agent）：30分钟打造你的首个 AI 智能体！

转载自DEV社区：

Agents 101: How to build your first AI Agent in 30 minutes!

Anmol Baranwal Posted on 2.8 • Edited on 4.14 • Originally published at copilotkit.ai

这篇文章较为详细的介绍了AI智能体及其一种构建方法，转载一下以后应该会一直翻看。同时，也学习一下这篇文章的一些写作技巧。

2025 年，我们正见证 AI 智能体的崛起。

完全构建出自己的智能体很复杂，需要掌握所有相关概念、框架和构建方法，这需要花费很多时间和精力。但好消息是，只是为应用程序添加智能体却很简单，接下来我将为你展示具体方法。

本文将教你如何在短短 30 分钟内构建首个 AI 智能体，即使你对 AI 智能体一无所知。

让我们开始吧。

本文涵盖的内容

简而言之，我们将详细探讨以下主题。

了解什么是 AI 智能体
一步步教你使用 Copilotkit 和 LangGraph 构建智能体
附真实案例及源代码

注：Copilotkit（构建 AI 助手的框架）近期与 LangChain 合作推出了 CoAgents，这正是本文即将使用的工具

1. 什么是 AI 智能体？

AI 智能体就像超级聪明的助手。你只需告诉它们需求，它们就能想办法完成任务！

大语言模型（LLM）充当着系统的核心大脑。当人工智能需要与外界沟通、获取数据或执行特定任务时，它可以借助工具——这些工具即外部资源或应用程序接口（API）。

AI 智能体能够规划并做出决策，甚至随着时间的推移不断自我进步。你可以将其视为一种数字实体，能够观察、思考并采取行动，就像人类与周围环境互动一样，只不过是以一种经过编程且有目的性的方式。

AI 智能体主要可分为两种类型：

反应型（Reactive）：对环境中的即时输入做出响应。
主动型（Proactive Agents ）：为实现长期目标进行前瞻性规划。

本图鸣谢 Abhishek Reddy (Medium)

核心组件

AI 智能体的核心由以下相互关联的组件构成，使其能够感知环境、进行推理、采取行动并持续学习：

感知模块（Perception）：从环境中收集并解析数据
推理模块（Reasoning）：通过分析信息来做出决策。
行动模块（Action）：根据已做出的决策执行任务。
学习模块（Learning）：利用机器学习算法从过往经验中适应并提升表现。
通信接口（Communication Interface）：通过自然语言处理(NLP)和协议与其他代理或系统交互。
记忆模块（Memory）：存储历史数据和知识以供未来使用。
特征分析（Profiling）代理从环境中收集数据的方式。

你会在不同地方找到不同的细节描述，但大体意思都差不多。若想了解更多，可查阅 simform 关于《什么是 AI 智能体》的指南。

大型环境中的 AI 智能体图示如下：

对 AI 智能体的误解

很多人其实对 AI 智能体存在误解。让我们明确 AI 智能体不具备哪些特性：

❌ 并非魔法：它们并不像人类那样"思考"，只是遵循既有的自动化模式。
❌ 并非总是准确：它们可能出现幻觉并犯错。

此外，并非所有场景都需要它们。比如当您已掌握所有可能的用户操作时，直接编码即可。例如用户点击按钮预订酒店房间→显示可用日期→确认预订，这种情况下完全不需要 AI 介入。

一个简单的经验法则：如果你的任务简单直接、基于规则或需要 100%准确率，AI 智能体就不是合适的选择。

既然我们已经了解了 AI 智能体，接下来就该动手构建一个了。

2. 逐步使用 Copilotkit 和 LangGraph 构建 AI 智能体

本节将介绍如何在几分钟内构建您的第一个智能代理。

CopilotKit 是一个将 AI 助手集成到产品中的框架，提供 AI 聊天、生成式 UI 和自动补全的 React 组件，以及通过用户行为数据增强 AI 智能体的运行环境（包含上下文理解、工具调用和技能学习）。该团队近期发布了处于测试阶段的 CoAgents 功能。

⭐️ 立即体验 CopilotKit ⭐️

通过 LangGraph SDK 与 CoAgents (Copilotkit) 的组合，开发者能快速为任何垂直领域构建此类应用。只需创建适配工作流程的 LangGraph agent ，再通过 CoAgents 集成自定义操作和生成式 UI 体验。

此外，得益于 LangGraph 技术，所有功能都集成在一个简洁的框架内，用于对应用内的AI智能体进行管理，您将获得一个完整套件，包括以下功能：

共享状态（智能体 ↔ 应用程序）
生成式UI
人机交互
实时的前端操作
智能体导向（LangGraph 检查点）

您可以在 copilotkit.ai/coagents 上阅读更多内容，该网站还配有说明图表帮助理解。

如需快速了解，请观看 Copilotkit 联合创始人 Atai 的 2 分钟讲解视频！

若想自行探索，可遵循官方快速入门指南。若不愿尝试也无妨，我将逐步详解所有操作。

若已拥有 LangGraph 智能体，可直接跳转至步骤3。这里我们将克隆初始代码库以便快速开始。

为避免本文篇幅过长，我不会涵盖每个细节概念。您可在文档的学习章节查阅相关术语、概念等内容。

步骤 1：克隆初始代码库

最开始我们需要搭建我们的 AI 智能体。

我们首先需要克隆 CopilotKit GitHub下的 coagents 启动代码库。

git clone https://github.com/CopilotKit/CopilotKit
cd CopilotKit/examples/coagents-starter/agent-py

我新建了一个干净的目录（通过复制粘贴），这样理解起来会容易得多。你可以按照相同的步骤操作克隆的代码库。

我们的目录结构将如下所示。 agent 目录将存放 LangGraph 智能体，而 ui 目录则包含我们的前端应用。

如果你还没有前端项目，可以使用 TypeScript 创建一个新的 Next.js 应用，然后安装 Copilotkit 的 react 包。在克隆的仓库中这些已经存在，所以你只需在 ui 目录下使用 pnpm i 安装依赖项即可。

// creates a nextjs app with typescript

npx create-next-app@latest ui --typescript

// install copilotkit packages

npm install @copilotkit/react-ui @copilotkit/react-core

CopilotKit 套件能让协作智能体与 React 状态值交互，并在应用内部做出决策。

你需要使用 pnpm run dev 命令来运行前端服务。

如果你想使用 LangGraph JS ，可以使用 agent-js 目录。在本文中，我都将使用 Python 版本( agent-py )。

之后，在 agent-py 目录中，使用 Poetry 安装项目依赖项。

cd agent/agent-py
poetry install

然后，使用命令运行演示： poetry run demo 。

步骤 2：添加必要的 API 密钥

在 agent-py 目录下创建一个 .env 文件。然后将您的 OpenAI API 密钥和 LangSmith API 密钥添加到 .env 文件中。（我已附上文档链接以便于参考）

遵循以下命名规范：

OPENAI_API_KEY=your_openai_api_key
LANGSMITH_API_KEY=your_langsmith_api_key

Langsmith API 密钥：

OpenAI API 密钥：

步骤 3：启动您的 LangGraph 智能体代理

您可以通过多种方式启动智能体，例如使用仅支持 Python 智能体的自托管方案（FastAPI），或按照官方生产环境指南部署到 LangGraph 平台。

本文范围内，我们将采用本地开发模式，使用 LangGraph 命令行工具启动开发服务器和 LangGraph Studio 会话。

使用此方法需要注册 LangSmith 账号。请确保系统已安装 docker，然后通过 pip install langgraph-cli 安装 CLI 工具。

在运行主命令前，需确认 CopilotKit 已安装。可执行以下命令完成安装。

python -m pip show copilotkit

若未安装，可通过 python -m pip install copilotkit 进行安装。

然后只需运行以下命令即可在本地启动服务。

langgraph dev --host localhost --port 8000
# our deployment URL will be http://localhost:8000

该命令会启动一个 LangGraph 开发服务器，并使用 langgraph.json 从这个文件中读取设置（如路由、节点、行为等）来配置应用程序。

如果运行成功，你将获得一个本地 LangGraph 工作室。它能帮助可视化 steps_node ，然后搜索结果、进行总结并提取关键要点。

你可以交互式地运行和测试不同流程，同时通过逐步执行来调试问题。

本地 LangGraph 工作室：

API 文档：

步骤 4：将您的 LangGraph 智能体连接至 CopilotKit

现在您需要通过自托管云运行时或 Copilot Cloud（推荐选项，本文采用此方案）将 LangGraph 智能体接入 CopilotKit。

使用 Copilot Cloud 时，需为 LangGraph 智能体配置远程接入端点。如需了解自托管方案（FastAPI）或 LangGraph 平台，可查阅相关文档。

我们将使用 LangGraph Studio 在本地进行设置。当你在本地运行 LangGraph 代理时，需要开启一个隧道以便 Copilot Cloud 能够与之连接。请使用以下命令：

npx copilotkit@latest dev --port 8000

你将获得安装 copilotkit 软件包的选项，以及通过 Copilot Cloud 进行身份验证的选项（若尚未认证）。

如你所见，本地隧道已启动并与 Copilot Cloud 完成对接！

您还将在 CopilotKit 云仪表板上收到确认信息。

CopilotKit 云端仪表盘：

步骤 5：设置 CopilotKit 提供程序

<CopilotKit> 组件必须包裹应用中所有需要 Copilot 感知的部分。多数情况下，最佳实践是将其放置在应用最外层，如 layout.tsx 所示。

该 API 密钥可在 ui/app/layout.tsx 中获取。您需要登录 copilotkit 云平台（cloud.copilotkit.ai）来获取此密钥。

import type { Metadata } from "next";

import { CopilotKit } from "@copilotkit/react-core";

import "@copilotkit/react-ui/styles.css";
import "./globals.css";

export const metadata: Metadata = {
  title: "CoAgents Starter",
  description: "CoAgents Starter",
};

export default function RootLayout({ children }: { children: any }) {
  return (
    <html lang="en">
      <body>
        {/* Use the public api key you got from Copilot Cloud  */}
        <CopilotKit
          agent="sample_agent" // lock the agent to the sample_agent since we only have one agent
          //  runtimeUrl="/api/copilotkit"
          showDevConsole={false}
          publicApiKey="<your-copilot-cloud-public-api-key>"
        >
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}

由于我们使用了 Copilot Cloud ，因此需要在 CopilotKit 组件中省略 runtimeUrl 属性，并提供有效的 API 密钥。

本示例仅使用单个代理，但如果您需要运行多个 LangGraph 代理，请参阅官方多代理指南。

步骤 6：设置 Copilot 用户界面

最后一步是使用 CopilotKit 的 UI 组件来渲染与智能体的聊天交互。通常情况下，这会与核心页面组件（如您的 page.tsx 文件）一起实现。

import "@copilotkit/react-ui/styles.css";
import { CopilotPopup } from "@copilotkit/react-ui";

export function YourApp() {
  return (
    <main>
      <h1>Your main content</h1>

      <CopilotPopup
        labels={{
            title: "Popup Assistant",
            initial: "Hi! I'm connected to an agent. How can I help?",
        }}
      />
    </main>
  );
}

在克隆的代码库中， CopilotSidebar 采用了恰当的样式处理。两种方式都完全可行，我选用这种写法是为了便于理解。

如果你在寻找其他聊天组件选项（ CopilotPopup 、 CopilotChat …），可以参考《智能聊天界面指南》。

大功告成！恭喜！🎉

你已成功将 LangGraph 智能体集成到应用中。现在可以尝试向你的智能体提问了。