AgentLab:可视化 Agent 编排实验台

在画布上拖拽编排 agent 工作流,并实时看着它执行。

后端 FastAPI + LangGraph:把画布 JSON 编译成 StateGraph,15 种节点
(模型/Agent/多Agent、工具/沙箱、分支/循环/子图、记忆/检索/整形、
人工介入/结构校验)。选 LangGraph 是因为可视化编排真正难的是暂停、
恢复和回放,而 checkpointer + interrupt() 正好把这几件事做在了底层。

前端 React + React Flow:节点元数据驱动属性面板与连接桩,运行时
节点高亮、边流动画、卡片内流式 token 全部由同一份事件流驱动。

关键实现:
- Agent 内工具审批用 @task 缓存模型调用,interrupt 重放时不重复计费
- 沙箱保持只读根文件系统,代码经 exec+base64 写入(put_archive 会被
  只读容器拒绝),断网、非 root、内存/CPU/超时限额
- 检索为向量与 BM25 混合,本地哈希 embedding 零配置可用
- 分支条件走 AST 白名单求值器;HTTP 工具逐 IP 拦截内网与元数据地址
- Mock provider 让无 API Key 也能跑通完整链路

7 个内置模板全部冒烟通过,含真实模型端到端验证。
This commit is contained in:
ThearchyHelios
2026-09-13 17:27:00 +08:00
commit 964eeaa829
89 changed files with 17280 additions and 0 deletions
+400
View File
@@ -0,0 +1,400 @@
import {
Bot, Braces, Brain, CheckCircle2, Code2, Database, FileInput, FileOutput,
GitBranch, Hand, Repeat, Search, Shuffle, Users, Wrench,
} from 'lucide-react'
import type { NodeType } from '../types'
export type FieldType =
| 'text' | 'textarea' | 'prompt' | 'code' | 'number' | 'select' | 'switch'
| 'json' | 'model' | 'tools' | 'skills' | 'collection'
| 'ioFields' | 'cases' | 'agents'
export interface FieldDef {
key: string
label: string
type: FieldType
placeholder?: string
help?: string
options?: { value: string; label: string }[]
min?: number
max?: number
step?: number
/** 只在满足条件时显示,避免面板一次糊一屏用不上的选项 */
when?: (config: Record<string, any>) => boolean
advanced?: boolean
}
export interface HandleDef {
id: string
label: string
color?: string
}
export interface NodeDef {
type: NodeType
label: string
category: string
description: string
icon: typeof Bot
hasTarget: boolean
/** 静态出口;branch/loop 这类由配置动态生成的返回 null */
sources: HandleDef[] | null
fields: FieldDef[]
defaults: Record<string, any>
}
const MODEL_FIELDS: FieldDef[] = [
{ key: 'model', label: '模型', type: 'model', help: '留空则用默认 provider' },
{
key: 'thinking', label: '思考模式', type: 'select', advanced: true,
options: [
{ value: '', label: '跟随模型默认' },
{ value: 'summarized', label: '开启并显示摘要' },
{ value: 'adaptive', label: '开启但不显示' },
{ value: 'off', label: '关闭' },
],
help: 'Claude 4.6+ 默认会先思考再回答,思考也消耗 token',
},
{
key: 'effort', label: '投入程度', type: 'select', advanced: true,
options: [
{ value: '', label: '默认' }, { value: 'low', label: 'low' },
{ value: 'medium', label: 'medium' }, { value: 'high', label: 'high' },
{ value: 'xhigh', label: 'xhigh' }, { value: 'max', label: 'max' },
],
},
{
key: 'temperature', label: '温度', type: 'number', min: 0, max: 2, step: 0.1, advanced: true,
help: 'Claude 4.6 之后的模型不支持,填了也会被自动忽略',
},
{ key: 'max_tokens', label: '最大输出 token', type: 'number', min: 1, advanced: true },
]
const COMMON_TAIL: FieldDef[] = [
{
key: 'assign_to', label: '结果存为变量', type: 'text', placeholder: '例如 result',
help: '下游用 {{ vars.变量名 }} 引用',
},
{ key: 'skip_if', label: '跳过条件', type: 'text', advanced: true, placeholder: 'vars.count == 0' },
{ key: 'retries', label: '失败重试次数', type: 'number', min: 0, max: 5, advanced: true },
{
key: 'on_error', label: '出错时', type: 'select', advanced: true,
options: [{ value: '', label: '中断整个运行' }, { value: 'continue', label: '记录错误并继续' }],
},
]
export const NODE_DEFS: Record<NodeType, NodeDef> = {
input: {
type: 'input', label: '输入', category: '起止', icon: FileInput,
description: '工作流入口,声明需要哪些输入',
hasTarget: false, sources: [{ id: 'out', label: '' }],
fields: [{ key: 'fields', label: '输入字段', type: 'ioFields' }],
defaults: { fields: [{ name: 'question', required: true }] },
},
output: {
type: 'output', label: '成果', category: '起止', icon: FileOutput,
description: '收集最终结构化成果',
hasTarget: true, sources: [],
fields: [{ key: 'fields', label: '成果字段', type: 'ioFields' }],
defaults: { fields: [{ name: '结果', value: '{{ last_message }}' }] },
},
llm: {
type: 'llm', label: '模型调用', category: '模型', icon: Brain,
description: '单次 LLM 调用,可要求结构化输出',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'system', label: '系统提示', type: 'textarea', placeholder: '你是…' },
{ key: 'prompt', label: '用户提示', type: 'prompt', placeholder: '{{ input.question }}' },
{ key: 'skills', label: '挂载 Skill', type: 'skills' },
...MODEL_FIELDS,
{
key: 'output_schema', label: '结构化输出 Schema', type: 'json', advanced: true,
help: '填了就强制模型按此 JSON Schema 返回',
},
{ key: 'use_history', label: '带上对话历史', type: 'switch', advanced: true },
...COMMON_TAIL,
],
defaults: { system: '', prompt: '{{ input.question }}' },
},
agent: {
type: 'agent', label: 'Agent', category: '模型', icon: Bot,
description: '带工具循环,自己决定调什么工具',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'system', label: '角色设定', type: 'textarea' },
{ key: 'prompt', label: '任务', type: 'prompt' },
{ key: 'tools', label: '可用工具', type: 'tools' },
{ key: 'skills', label: '挂载 Skill', type: 'skills' },
{ key: 'max_steps', label: '最大步数', type: 'number', min: 1, max: 25 },
{
key: 'approval', label: '工具审批', type: 'select',
options: [
{ value: 'dangerous', label: '仅危险工具需要确认' },
{ value: 'always', label: '每次调用都确认' },
{ value: 'never', label: '全部自动放行' },
],
help: '需要确认时运行会暂停,等你在审批面板放行',
},
...MODEL_FIELDS,
...COMMON_TAIL,
],
defaults: { max_steps: 8, approval: 'dangerous', tools: [] },
},
supervisor: {
type: 'supervisor', label: '多 Agent 协作', category: '模型', icon: Users,
description: '调度者按进展把任务分派给多个专家',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'goal', label: '团队目标', type: 'prompt' },
{ key: 'agents', label: '团队成员', type: 'agents' },
{ key: 'max_rounds', label: '最大轮次', type: 'number', min: 1, max: 25 },
...MODEL_FIELDS,
...COMMON_TAIL,
],
defaults: { max_rounds: 6, agents: [] },
},
tool: {
type: 'tool', label: '调用工具', category: '执行', icon: Wrench,
description: '直接调用一个指定工具',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'tool', label: '工具', type: 'tools', help: '只能选一个' },
{ key: 'args', label: '参数', type: 'json', help: '值里可以用 {{ }} 引用上游' },
{
key: 'approval', label: '执行前确认', type: 'select',
options: [
{ value: 'dangerous', label: '危险工具需要确认' },
{ value: 'always', label: '总是确认' },
{ value: 'never', label: '不确认' },
],
},
...COMMON_TAIL,
],
defaults: { args: {}, approval: 'dangerous' },
},
code: {
type: 'code', label: '沙箱代码', category: '执行', icon: Code2,
description: '在隔离容器里执行代码',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{
key: 'language', label: '语言', type: 'select',
options: [
{ value: 'python', label: 'Python' }, { value: 'bash', label: 'Bash' },
{ value: 'node', label: 'Node.js' },
],
},
{ key: 'code', label: '代码', type: 'code', help: '代码里可以用 {{ }} 插值' },
{ key: 'timeout', label: '超时(秒)', type: 'number', min: 1, max: 300 },
{ key: 'memory_mb', label: '内存上限 MB', type: 'number', min: 64, max: 4096, advanced: true },
{ key: 'network', label: '允许联网', type: 'switch', help: '默认断网' },
{
key: 'approval', label: '执行前确认', type: 'select', advanced: true,
options: [{ value: 'never', label: '不确认' }, { value: 'always', label: '总是确认(可改代码)' }],
},
{ key: 'fail_fast', label: '执行失败即中断', type: 'switch', advanced: true },
...COMMON_TAIL,
],
defaults: { language: 'python', code: 'print("hello")', timeout: 30, network: false, fail_fast: true },
},
branch: {
type: 'branch', label: '条件分支', category: '控制', icon: GitBranch,
description: '按条件或语义分类走不同的路',
hasTarget: true, sources: null,
fields: [
{
key: 'mode', label: '判断方式', type: 'select',
options: [
{ value: 'expression', label: '表达式判断' },
{ value: 'llm', label: '让模型分类' },
],
},
{ key: 'cases', label: '分支', type: 'cases' },
{
key: 'input', label: '待分类内容', type: 'prompt',
when: (c) => c.mode === 'llm', placeholder: '{{ last_message }}',
},
{ key: 'instruction', label: '分类说明', type: 'textarea', when: (c) => c.mode === 'llm' },
...MODEL_FIELDS.filter((f) => f.key === 'model').map((f) => ({
...f, when: (c: any) => c.mode === 'llm',
})),
...COMMON_TAIL.filter((f) => f.key !== 'assign_to'),
],
defaults: { mode: 'expression', cases: [{ key: 'yes', condition: '', label: '' }] },
},
loop: {
type: 'loop', label: '循环', category: '控制', icon: Repeat,
description: '遍历列表或按条件重复执行',
hasTarget: true, sources: null,
fields: [
{
key: 'mode', label: '循环方式', type: 'select',
options: [
{ value: 'foreach', label: '遍历列表' },
{ value: 'while', label: '条件成立时重复' },
],
},
{
key: 'items', label: '列表来源', type: 'text', when: (c) => c.mode !== 'while',
placeholder: '{{ input.items }}',
},
{ key: 'item_var', label: '当前项变量名', type: 'text', when: (c) => c.mode !== 'while' },
{
key: 'condition', label: '继续条件', type: 'text', when: (c) => c.mode === 'while',
placeholder: 'vars.done != true',
},
{ key: 'max_iterations', label: '最大迭代次数', type: 'number', min: 1, max: 100 },
],
defaults: { mode: 'foreach', item_var: 'item', max_iterations: 10 },
},
subgraph: {
type: 'subgraph', label: '子工作流', category: '控制', icon: Braces,
description: '把另一张工作流当成一个节点嵌进来',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'workflow_id', label: '工作流', type: 'select', options: [] },
{ key: 'input', label: '传入参数', type: 'json' },
...COMMON_TAIL,
],
defaults: { input: {} },
},
memory: {
type: 'memory', label: '长期记忆', category: '上下文', icon: Database,
description: '读取或写入跨运行的长期记忆',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{
key: 'action', label: '操作', type: 'select',
options: [
{ value: 'recall', label: '回忆(检索)' },
{ value: 'write', label: '记住(写入)' },
{ value: 'clear', label: '清空该作用域' },
],
},
{ key: 'scope', label: '作用域', type: 'text', placeholder: 'default' },
{ key: 'query', label: '回忆什么', type: 'prompt', when: (c) => c.action !== 'write' && c.action !== 'clear' },
{ key: 'limit', label: '返回条数', type: 'number', min: 1, max: 20, when: (c) => c.action !== 'write' },
{ key: 'content', label: '记住的内容', type: 'prompt', when: (c) => c.action === 'write' },
{
key: 'kind', label: '记忆类型', type: 'select', when: (c) => c.action === 'write',
options: [
{ value: 'fact', label: '事实' }, { value: 'preference', label: '偏好' },
{ value: 'episode', label: '事件' },
],
},
{ key: 'importance', label: '重要程度', type: 'number', min: 0, max: 1, step: 0.1, when: (c) => c.action === 'write' },
...COMMON_TAIL,
],
defaults: { action: 'recall', scope: 'default', limit: 5, query: '{{ last_message }}' },
},
retrieve: {
type: 'retrieve', label: '知识检索', category: '上下文', icon: Search,
description: '从知识库里混合检索相关片段',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'query', label: '检索问题', type: 'prompt' },
{ key: 'collection', label: '知识库', type: 'collection' },
{ key: 'limit', label: '返回片段数', type: 'number', min: 1, max: 20 },
{
key: 'alpha', label: '向量 vs 关键词', type: 'number', min: 0, max: 1, step: 0.1,
help: '1 = 纯语义相似,0 = 纯关键词匹配',
},
{ key: 'min_score', label: '最低分数', type: 'number', min: 0, max: 1, step: 0.05, advanced: true },
...COMMON_TAIL,
],
defaults: { query: '{{ last_message }}', collection: 'default', limit: 5, alpha: 0.5 },
},
transform: {
type: 'transform', label: '数据整形', category: '上下文', icon: Shuffle,
description: '不调模型,直接把数据揉成下游要的形状',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{
key: 'mode', label: '方式', type: 'select',
options: [
{ value: 'template', label: '文本模板' },
{ value: 'expression', label: '表达式' },
{ value: 'json', label: 'JSON 模板' },
],
},
{ key: 'template', label: '模板', type: 'textarea', when: (c) => c.mode !== 'expression' },
{
key: 'expression', label: '表达式', type: 'text', when: (c) => c.mode === 'expression',
placeholder: "len(vars.items)",
},
...COMMON_TAIL,
],
defaults: { mode: 'template', template: '{{ last_message }}' },
},
human: {
type: 'human', label: '人工介入', category: '把关', icon: Hand,
description: '暂停运行,等人确认或补充信息',
hasTarget: true, sources: null,
fields: [
{
key: 'mode', label: '介入方式', type: 'select',
options: [
{ value: 'approve', label: '批准 / 驳回' },
{ value: 'input', label: '补充输入' },
{ value: 'edit', label: '编辑草稿' },
],
},
{ key: 'title', label: '标题', type: 'text' },
{ key: 'message', label: '给人看的内容', type: 'prompt' },
{ key: 'draft', label: '草稿内容', type: 'prompt', when: (c) => c.mode === 'edit' },
{ key: 'stop_on_reject', label: '驳回即终止运行', type: 'switch', when: (c) => c.mode === 'approve' },
...COMMON_TAIL,
],
defaults: { mode: 'approve', title: '需要你确认', message: '{{ last_message }}' },
},
validate: {
type: 'validate', label: '结构校验', category: '把关', icon: CheckCircle2,
description: '按 JSON Schema 校验,不合格可让模型自动返工',
hasTarget: true, sources: [{ id: 'out', label: '' }],
fields: [
{ key: 'source', label: '待校验内容', type: 'prompt', placeholder: '{{ last_message }}' },
{ key: 'schema', label: 'JSON Schema', type: 'json' },
{ key: 'max_retries', label: '最多返工次数', type: 'number', min: 0, max: 5 },
{ key: 'repair_with_llm', label: '让模型修复', type: 'switch' },
{ key: 'fail_fast', label: '校验失败即中断', type: 'switch' },
...COMMON_TAIL,
],
defaults: {
source: '{{ last_message }}', max_retries: 2, repair_with_llm: true, fail_fast: true,
schema: { type: 'object', properties: {}, required: [] },
},
},
}
export const NODE_CATEGORIES = ['起止', '模型', '执行', '控制', '上下文', '把关']
/** branch / loop / human 的出口由配置决定,这里统一算出来。 */
export function sourceHandles(type: NodeType, config: Record<string, any>): HandleDef[] {
const def = NODE_DEFS[type]
if (def.sources) return def.sources
if (type === 'branch') {
const cases = (config.cases ?? []) as { key?: string; label?: string }[]
return [
...cases
.filter((c) => c.key)
.map((c) => ({ id: c.key!, label: c.label || c.key!, color: 'var(--ok)' })),
{ id: 'default', label: '其他', color: 'var(--text-faint)' },
]
}
if (type === 'loop') {
return [
{ id: 'body', label: '循环体', color: 'var(--nt)' },
{ id: 'done', label: '结束', color: 'var(--text-faint)' },
]
}
if (type === 'human') {
if (config.mode === 'approve') {
return [
{ id: 'approved', label: '通过', color: 'var(--ok)' },
{ id: 'rejected', label: '驳回', color: 'var(--err)' },
]
}
return [{ id: 'out', label: '' }]
}
return [{ id: 'out', label: '' }]
}