LangChain Agent 使用指南

概述

本文档为使用 LangChain 构建自然语言生成表单的 Agent 提供参考数据和配置指南。

Agent 任务定义

任务：将用户的自然语言描述转换为表单字段配置 JSON

输入：自然语言描述 输出：表单字段配置数组

自然语言到组件映射

基础输入类

用户关键词	组件类型	tag	配置要点
姓名、名字	NameField	name	必填通常为 true
性别	GenderField	gender	选项：男/女
手机号、电话	PhoneField	phone	自动验证11位
邮箱	EmailField	email	自动验证格式
身份证	IdentityField	id_card	自动验证格式
数字、数量	NumberField	number	整数类型
单行文本、输入	TextField	input	最多255字符
多行文本、描述	TextareaField	textarea	支持自动高度

选择类

用户关键词	组件类型	tag	数据结构
单选、单项选择	RadioField	radio	options 数组
多选、多项选择	CheckboxField	checkbox	options 数组
下拉、选择	PickerField	select	options 数组
省、市、区、地址	AreaPickerField	address	三级联动

日期时间类

用户关键词	组件类型	tag	备注
日期、出生日期	DatePickerField	date	-
时间	TimePickerField	time	-
日期时间、开始时间	DateTimePickerField	datetime	-
日历	CalendarField	calendar	日历形式

上传类

用户关键词	组件类型	tag	配置参数
图片、照片、上传图	ImageUploaderField	image_uploader	max_count, max_size
文件、附件、上传	FileUploaderField	file_uploader	max_count, max_size

特殊功能类

用户关键词	组件类型	tag	备注
签名、签字、电子签名	SignField	sign	手写签名板
评分、打分、星级	RatePickerField	rate	支持 x_score 显示
预约、时间段	AppointmentField	appointment	复杂配置
说明、富文本	NoteField	note	HTML 内容
分割线、分隔	DividerField	divider	-
跑马灯、公告	MarqueeField	marquee	滚动文字
规则、说明	RuleField	rule	支持弹窗
按钮	ButtonField	button	自定义按钮

高级类

用户关键词	组件类型	tag	备注
表格、清单	TableField	table_editor	动态表格
分组、集合	GroupField	group	field_groups 数组
树形选择、组织	OrgPickerField	org_picker	树结构
组别、义工组	VolunteerGroupField	volunteer_group	义工组选择

必填识别

强必填关键词

• 必填、必须、一定要、强制
• 不可缺少、不能为空
• 必须提供、务必填写

可选关键词

• 可选、非必须、非强制
• 选填、可以不填
• 如果有、尽量填写

默认规则

• 姓名通常必填
• 手机号通常必填
• 附件类通常选填
• 说明文字通常选填

数量识别

图片上传数量

• "一张图"、"1张" → max_count: 1
• "三张图"、"3张" → max_count: 3
• "最多5张" → max_count: 5
• "多张"、"若干" → max_count: 9（默认）

文件大小限制

• "5MB以内"、"小于5M" → max_size: 5
• "10MB" → max_size: 10

选项提取

单选/多选选项提取

用户输入："性别：男、女、其他"

提取结果：

options: [
  { title: "男", value: "男" },
  { title: "女", value: "女" },
  { title: "其他", value: "其他" }
]

带描述的选项

用户输入："同意（详见规则）、不同意"

提取结果：

options: [
  {
    title: "同意",
    value: "agree",
    desc_text: "点击查看详细规则",
    desc_type: "text",
    desc_btn_name: "详见规则"
  },
  {
    title: "不同意",
    value: "disagree"
  }
]

带补充输入的选项

用户输入："其他（需说明）"

提取结果：

options: [
  {
    title: "其他",
    value: "other",
    is_input: true,
    input_required: true,
    input_placeholder: "请说明具体情况"
  }
]

复杂需求处理

分组需求

用户输入："物品信息（包含物品名称和数量）"

处理方式：

1. 识别为 group 类型
2. 创建 field_groups 数组
3. 每个子项作为独立字段

{
  key: "field_1",
  value: "",
  component_props: {
    tag: "group",
    label: "物品信息",
    field_groups: [
      {
        tag: "input",
        label: "物品名称",
        field_name: "field_1_1",
        group_field_name: "field_1"
      },
      {
        tag: "number",
        label: "数量",
        field_name: "field_1_2",
        group_field_name: "field_1"
      }
    ]
  }
}

选项依赖

用户输入："选择'其他'时需要输入补充信息"

处理方式：

• 在对应选项设置 is_input: true
• 设置 input_required 根据上下文判断

提示信息

用户输入："用户名（4-16个字符，字母数字）"

处理方式：

• label: "用户名"
• note: "4-16个字符，支持字母、数字、下划线"

Prompt 模板

系统提示词

FORM_BUILDER_SYSTEM_PROMPT = """
你是一个表单配置生成专家。你的任务是将用户的自然语言描述转换为符合规范的表单字段配置JSON。

## 输出格式

返回一个JSON数组，每个元素代表一个表单字段。

## 字段结构

每个字段必须包含：
- key: 字段唯一标识（格式：field_序号）
- value: 初始值
- component_props: 组件属性对象
  - tag: 组件类型
  - label: 显示名称
  - required: 是否必填
  - 其他属性根据组件类型而定

## 组件类型选择规则

根据用户描述选择最合适的组件类型：
- 文本输入：input（单行）、textarea（多行）、number（数字）
- 选择类：radio（单选）、checkbox（多选）、select（下拉）
- 日期时间：date、time、datetime
- 上传类：image_uploader、file_uploader
- 特殊：name、gender、phone、email、id_card、sign、rate等

## 选项提取规则

当用户列出选项时：
1. 识别是单选还是多选
2. 提取每个选项的标题和值
3. 检测是否有补充信息需求
4. 检测是否有描述信息

## 必填识别规则

- "必填、必须、一定要" → required: true
- "可选、选填" → required: false
- 姓名、手机号等基础信息通常必填
- 说明、附件类通常选填

请根据用户输入生成相应的表单配置。
"""

用户输入示例

# 示例1：简单表单
user_input = "创建一个报名表单，包含姓名（必填）、性别（必填，男/女）、手机号（必填）"

# 示例2：带选项
user_input = "报名类型，单选，必填，选项：个人报名、团队报名"

# 示例3：图片上传
user_input = "上传证件照，最多3张，每张不超过5MB，必填"

# 示例4：分组
user_input = "物品清单，包含物品名称（必填）和数量（必填）"

# 示例5：复杂需求
user_input = "活动报名表，包含：姓名（必填）、性别（男/女/其他，其他需说明）、手机号（必填）、兴趣爱好（多选：运动、阅读、音乐、旅游）、活动日期（必填）、上传照片（最多3张）、本人签名（必填）"

LangChain 工具调用

推荐使用 LangChain 的工具

1. Structured Output - 确保输出格式正确
2. Few-shot Prompting - 提供示例
3. Output Parser - 解析 JSON 输出

代码示例

from langchain.output_parsers import PydanticOutputParser
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field
from typing import List, Optional

class FormField(BaseModel):
    key: str = Field(description="字段唯一标识")
    tag: str = Field(description="组件类型")
    label: str = Field(description="显示名称")
    required: bool = Field(description="是否必填")
    placeholder: Optional[str] = Field(default="", description="占位符")
    options: Optional[List[dict]] = Field(default=None, description="选项列表")
    max_count: Optional[int] = Field(default=None, description="最大上传数量")
    max_size: Optional[int] = Field(default=None, description="最大文件大小")

class FormConfiguration(BaseModel):
    fields: List[FormField] = Field(description="表单字段列表")

# 创建解析器
parser = PydanticOutputParser(pydantic_object=FormConfiguration)

# 创建提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", FORM_BUILDER_SYSTEM_PROMPT),
    ("user", "{user_input}")
])

# 创建链
chain = prompt | llm | parser

# 调用
result = chain.invoke({"user_input": "创建一个用户信息表单..."})

验证和错误处理

输出验证

生成的 JSON 需要验证：

1. 结构验证

   • 是否是有效的 JSON 数组
   • 每个字段是否包含必需属性

2. 类型验证

   • tag 值是否在支持的组件列表中
   • required 是否为布尔值
   • options 是否为数组

3. 业务验证

   • 必填字段是否合理
   • 选项是否为空
   • 数量限制是否合理

常见错误处理

错误	处理方式
无法识别组件类型	询问用户具体需求
选项描述不清晰	提供选项模板让用户选择
必填不明确	默认为选填，提示用户确认
数量限制缺失	使用默认值（图片：3，文件：5）

完整工作流程

用户输入
    ↓
意图识别（新增/修改/查询）
    ↓
实体提取（字段名、组件类型、选项）
    ↓
配置生成（生成 component_props）
    ↓
格式验证（JSON 结构、类型检查）
    ↓
结果输出（表单配置 JSON）

最佳实践

1. 逐步确认：复杂需求分步确认，而非一次性生成
2. 提供示例：让用户选择最接近的示例
3. 默认值策略：不确定时使用保守的默认值
4. 错误友好：错误信息要具体指出问题和解决方案