LangFlow-AgentComponent 组件使用指南

AgentComponent 使用指南

一、组件概述

1.1 基本信息

属性	值
名称	Agent
显示名	Agent
描述	定义 Agent 的指令、连接 LLM 模型、使用工具完成任务的智能助手
图标	bot
文档链接	LangFlow Agents 文档
分类	LLM Components (Language Model Components)

1.2 核心功能

AgentComponent 允许用户：

1. 配置大型语言模型（LLM）
2. 添加可用工具（Tools）
3. 设置系统指令和输出格式
4. 定义 Agent 任务完成方式

---

二、核心架构

2.1 组件继承关系

┌────────────────────────────────────────────────────────────┐
│              LCToolsAgentComponent            │
│           LangChain 工具调用框架                │
│  ┌──────────────────────────────────┐   │
│  │  ToolCallingAgentComponent        │   │
│  └───────────────────────────────────┘   │
│             ↓ (继承)                        │   │
└────────────────────────────────────────────────────┘

继承链：

langflow.base.agents.agent
       ↓
langflow.base.agents.LCToolsAgentComponent
       ↓
langchain_core.agents.AgentExecutor (基础类)
       ↓
AgentComponent

2.2 核心工作流程

┌─────────────────────────────────────────────────────────┐
│                  AgentComponent                   │
│                                                 │
│  ┌─────────────┐  ┌──────────────┐   │
│  │   1. 获取   │  │   2. 构建      │   │
│  │   - LLM 模型 │  │   - 创建 Agent  │   │
│  │   - 获取内存   │   │   - 执行 Agent  │   │
│  │   - 获取工具   │   │   - 返回响应      │   │
│  └─────────────┘  └──────────────┘   │
│                      ↓                         │
│               ┌──────────────────┐    │
│               │   Structured Output  │   │
│               │    - 验证 Schema      │    │
│               │    - 包装为 Message   │    │
│               └───────────────────┘    │
│                        ↓                         │
│                  最终 Message 输出                  │
└─────────────────────────────────────────────────────┘

---

三、输入参数详解

3.1 基础配置

参数	类型	默认值	说明
agent_llm	Dropdown	OpenAI	模型提供商 (Anthropic/Google/OpenAI)
system_prompt	MultilineText	见下文	Agent 系统指令
n_messages	Int	100	聊天历史消息数量
format_instructions	MultilineText	见下文	输出格式指令
output_schema	TableInput	[]	结构化输出 Schema 定义
add_current_date_tool	Bool	True	是否添加获取当前日期工具

3.2 高级参数（OpenAI 特有）

参数	类型	说明
openai_api_base	String	https://api.openai.com/v1	OpenAI API 基础 URL
api_key	String	-	OpenAI API 密钥
temperature	Slider	0.1	温度参数 (0.1-2.0)
max_retries	Int	-	最大重试次数
timeout	Int	700	请求超时时间（秒）
handle_parsing_errors	Bool	-	是否处理解析错误
verbose	Bool	-	详细日志输出

3.3 模型提供商列表

提供商	模型示例
Anthropic	claude-3-opus-20240229, claude-3-sonnet-20240207
Google Generative AI	gemini-2.0-flash-exp, gemini-pro
OpenAI	gpt-4o-mini, gpt-4, gpt-4-turbo

---

四、支持的模型提供商

4.1 Anthropic

配置字段	说明
component_class	实现类	Anthropic 模型组件
inputs	需要	API Key, Base URL, Temperature 等
prefix	-	配置参数前缀

4.2 Google Generative AI

配置字段	说明
component_class	实现类	Gemini 模型组件
inputs	需要	API Key, Model Name, Generation Config 等
prefix	-	配置参数前缀

4.3 OpenAI

配置字段	说明
component_class	实现类	GPT 模型组件
inputs	需要	API Key, Model Name, Temperature 等
prefix	openai	配置参数前缀

---

五、系统指令

5.1 System Prompt

定义 Agent 的角色、能力和行为约束：

默认模板：
You are a helpful assistant that can use tools to answer questions and perform tasks.

关键元素：

元素	说明	示例
角色定义	AI 的身份和目标	"You are a customer service assistant..."
能力范围	可用的工具和能力	"You have access to the following tools..."
任务目标	主要任务和子任务	"Your task is to provide accurate information..."
约束条件	不能做什么	"Do not..."
输出格式	期望的响应格式	"Extract ALL relevant instances..."

5.2 Format Instructions

定义结构化输出的格式和验证规则：

默认模板：
You are an AI that extracts structured JSON objects from unstructured text. Use a predefined schema with expected types (str, int, float, bool, dict). Extract ALL relevant instances that match the schema - if multiple patterns exist, capture them all. Fill missing or ambiguous values with defaults: null for missing values. Remove exact duplicates but keep variations that have different field values. Always return valid JSON in expected format, never throw errors. If multiple objects can be extracted, return them all in structured format.

Schema 验证规则：

规则	说明
提取所有匹配实例	支持多个相同的键
填充缺失值	使用 null 作为默认值
去除精确重复	保留不同值的变体
始终返回 JSON	始终返回有效的 JSON，不抛出错误

5.3 Output Schema

通过表格定义输出字段结构：

字段名	类型	默认	说明
name	String	field	输出字段名称
description	String	description of field	字段描述
type	String	str	数据类型（str/int/float/bool/dict）
multiple	Boolean	False	是否为列表
edit_mode	Inline	INLINE	编辑模式

内置 Schema 验证：

• 名称: name, description, type, multiple

---

六、工具集成

6.1 工具动态加载

Agent 会自动扫描并连接可用的工具：

工具添加流程：
1. 用户连接工具到 Agent
2. Agent 调用 `_build_tools_names()` 动态生成工具列表
3. 工具列表通过 `Call_Agent` 传递给 LLM

6.2 支持的工具类型

工具类型	说明	示例
PythonCodeStructuredTool	执行 Python 代码	计算器、HTTP 请求
CalculatorComponent	数学计算	加、减、乘、除
URLComponent	网页抓取	爬取网页内容
ChatInput/ChatOutput	聊天输入输出	发送/接收消息
自定义组件	任何 LangFlow 组件	文件处理、API 调用等

6.3 工具元数据

通过 tools_metadata 参数可以为每个工具添加：

{
  "expression": {
    "args": {
      "expression": {
        "description": "The arithmetic expression to evaluate (e.g., '4*4*(33/22)+12-20').",
        "title": "Expression"
      }
    },
    "description": "CalculatorComponent. evaluate_expression() - Perform basic arithmetic operations on a given expression."
  }
}

---

七、记忆管理

7.1 聊天历史

| 参数 | 类型 | 默认 | 说明 | |------|------|------| | n_messages | Int | 100 | 检索的消息数量 | | order | String | Ascending | 检索顺序（升序） |

7.2 会话 ID

通过 session_id 参数维护多会话隔离。

7.3 发送者配置

参数	选项	说明
Machine	由 AI 发送
User	由用户发送

---

八、输出处理

8.1 输出流程

用户输入
    ↓
根据输出格式配置
    ↓
Schema 验证 (可选）
    ↓
Structured Chat (如果需要 JSON 输出）
    ↓
验证/格式化输出
    ↓
返回 Message 对象

8.2 输出类型判断

Agent 根据配置决定使用哪种输出模式：

模式	条件	说明
Structured Chat	有 Output Schema	使用结构化输出，进行 Schema 验证
Regular Chat	无 Output Schema	普通聊天模式，返回原始文本

8.3 JSON 响应示例

当使用结构化输出时，有效响应格式：

{
  "result": "计算成功",
  "total": 99.99,
  "currency": "CNY"
}

---

九、使用案例

案例 1：简单工具调用 Agent

场景描述

创建一个可以使用计算器和网页抓取工具的 AI 助手。

Langflow 配置

基础配置：

• agent_llm: OpenAI
• openai_api_base: https://api.openai.com/v1
• api_key: sk-xxx...（在 UI 中设置）
• system_prompt: 你是一个智能助手，可以使用工具来回答问题和完成任务。

添加工具：

1. 连接一个 CalculatorComponent（计算器）
2. 连接一个 URLComponent（网页抓取）

预期交互

用户: 今天的天气怎么样？

Agent: 让我来帮你查一下。

[调用 Calculator 计算 4*25]
[调用 URL 爬取天气信息]

Agent: 今天的天气是晴天，温度25度。

用户: 帮我计算 123 * 456。

Agent: 计算结果是 56088。

---

案例 2：结构化输出 Agent

场景描述

创建一个能够返回结构化 JSON 数据的 Agent，用于数据分析。

Output Schema 配置

字段 1: name

• name: result
• description: 分析结果描述
• type: str

字段 2: type

• type: str
• description: 数据类型
• options: ["str", "int", "float", "bool", "dict"]

字段 3: count

• name: count
• description: 数量统计
• type: int

字段 4: mean

• name: mean
• description: 平均值
• type: float

Format Instructions

你是一个数据分析 AI，负责分析用户输入的数据。
Extract only the JSON schema.
Return it as valid JSON.

Input:
包含数据列表或原始文本。

Output:
必须包含以下字段：
- result: 分析结果描述
- count: 数据点数量 (int)
- mean: 平均值 (float)

预期交互

用户: 分析这个销售数据列表 [100, 150, 200, 175, 120]

Agent: {
  "result": "销售数据分析完成",
  "count": 5,
  "mean": 149.0
}

---

案例 3：网页内容获取 Agent

场景描述

创建一个 Agent，可以从指定的 URL 网页抓取内容并返回给用户。

URLComponent 配置

urls: https://example.com/page1
      https://example.com/page2

max_depth: 2
format: Text

预期交互

用户: 获取 example.com 的内容

Agent: [抓取了以下内容...]

Page 1: 这是页面1的标题内容

Page 2: 这是页面2的内容...

---

案例 4：多工具协作 Agent

场景描述

创建一个可以根据问题类型选择不同工具的智能 Agent。

工具配置

工具 1: SearchAgent（搜索）

• 查询特定信息

工具 2: CalculatorComponent（计算）

• 执行数学运算

工具 3: URLComponent（抓取）

• 获取网页内容

预期交互

用户: 2024年的巴黎奥运会什么时候举办？

Agent: [调用 SearchAgent 搜索]
搜索结果: 2024年巴黎奥运会将于7月26日开幕

用户: 帮我计算从现在到开幕还有多少天？

Agent: [调用 CalculatorComponent 计算]
今天是2026年1月15日，还有193天

---

十、高级特性

10.1 错误处理

错误类型	处理方式
模型初始化失败	返回明确的错误消息	"No language model selected"
JSON 解析错误	回退到原始文本	返回 {content: ..., error: ...}
工具调用失败	包含错误信息但不中断流程	返回部分结果

10.2 动态参数切换

当切换不同的模型提供商时：

操作	行为
OpenAI → Google	自动切换 API 配置和输入字段
任何 → Anthropic	清除现有字段，添加新字段
Custom → 标准	显示"连接其他模型"选项

10.3 输出格式化

通过 data_template 参数控制输出格式：

| 模板变量 | 说明 | 示例 | |----------|------| | {text} | 原始 JSON 文本作为输出 | {result: "处理完成"} | | {data.text} | 包装在 Markdown 代码块中 | json\n{result: ...}\n |

---

十一、最佳实践

11.1 性能优化

建议	说明
控制历史消息数量	设置合理的 n_messages 值	默认 100 通常足够
选择合适的模型	根据任务复杂度选择	简单任务用小模型
使用结构化输出	需要时才启用 Schema 验证	开启解析时间更长

11.2 安全建议

建议	说明
API Key 管理	使用环境变量或加密存储	不要在代码中硬编码
错误处理	捕获所有异常并记录	便于排查问题
内容安全	使用 System Prompt 限制 Agent 能力范围

11.3 提示词工程

建议	说明
清晰的角色定义	明确说明 Agent 的身份和能力边界
任务导向的指令	具体描述 Agent 应该做什么，而非泛泛的"做一个助手"
示例输出	提供输出格式示例	减少模型理解偏差

---

十二、常见问题排查

12.1 模型连接问题

症状	可能原因	解决方案
无响应	检查 API Key 是否正确	验证模型提供商配置
响应超时	增加 timeout 参数值	默认 700 秒
401/429 错误	检查 OpenAI API Base URL 是否正确	应为 https://api.openai.com/v1

12.2 工具问题

症状	可能原因	解决方案
工具未被识别	检查工具元数据是否正确配置	确保 display_name 和 name 正确设置
工具调用失败	查看错误日志了解具体原因	可能是 API 不可用或参数错误

12.3 输出格式问题

症状	可能原因	解决方案
JSON 解析失败	检查模型是否支持 JSON 模式	确保使用 Structured Chat
Schema 验证错误	检查 Output Schema 字段定义	确保 type 字段值正确
多行输出	调整 Format Instructions	使用单行格式描述

---

十三、源码位置

文件	路径	说明
组件定义	src/base/langflow/components/agents/agent.py	AgentComponent 核心逻辑
基础 Agent 类	src/base/langflow/base/agents/agent.py	LCToolsAgentComponent 基类
示例项目	src/base/langflow/initial_setup/starter_projects/	各种 Agent 模板

---

文档更新时间: 2026-01-15 适用版本: Langflow v1.6.9+