支持MCP的多智能体框架,用于声明式YAML驱动的智能体工作流,结合CodeQL集成,应用于AI辅助代码审计、漏洞分类和安全研究。
Security Lab Taskflow Agent 是一个支持 MCP 的多 Agent 框架,用于声明式、由 YAML 驱动的 Agent 工作流。
它构建于 OpenAI Agents SDK 之上,使用 Pydantic 进行语法验证,并使用 Jinja2 进行模板渲染。
Taskflow Agent 利用类似 GitHub Workflow 的基于 YAML 的语法,使用一组 Agent 来执行一系列任务。
它的主要价值主张是作为一款 CLI 工具,让用户能够快速定义和编写 Agent 工作流脚本,而无需编写任何代码。
Agent 通过人格进行定义,它们接收任务以完成,并获得一组工具。
Agent 可以通过所谓的任务流协作完成一系列任务。
你可以在此处找到任务流语法的详细概述,并在此处找到示例任务流。
┌─────────────────────────────────────────────────────┐
│ CLI (cli.py) │
│ Typer-based entry point: -p, -t, -l, -g, -m, --resume, --lint│
└─────────────────────┬───────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ Runner (runner.py) │
│ Taskflow execution loop, model resolution, │
│ template rendering, session checkpointing │
└─────────────────────┬───────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ MCP Lifecycle (mcp_lifecycle.py) │
│ Server connection, cleanup, process management │
└─────────────────────┬───────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ Agent (agent.py) │
│ TaskAgent wrapper, hooks, OpenAI Agents SDK bridge │
└─────────────────────────────────────────────────────┘
Supporting modules:
models.py — Pydantic v2 grammar models (validation)
session.py — Task-level checkpoint / resume
available_tools.py — YAML resource loader with caching
template_utils.py — Jinja2 template environment
mcp_utils.py — MCP client parameter resolution
mcp_transport.py — MCP transport implementations (stdio, streamable)
mcp_prompt.py — System prompt construction
prompt_parser.py — Legacy prompt argument parser
capi.py — AI API endpoint and token management
path_utils.py — Platform-aware data/log directories
该 agent 同时支持 Chat Completions 和 Responses 两种 OpenAI API。
API 类型可以在全局配置,也可以在 model_config 文件中按模型单独配置:
seclab-taskflow-agent:
version: "1.0"
filetype: model_config
api_type: chat_completions # default for all models
models:
gpt_default: gpt-4.1
gpt_responses: gpt-5.1
model_settings:
gpt_responses:
api_type: responses # override for this model
endpoint: https://api.githubcopilot.com
token: CAPI_TOKEN # env var name containing the API key
每个模型的 model_settings 可以包含:
api_type — "chat_completions"(默认)或 "responses"endpoint — 针对此模型的 API 基础 URL 覆盖token — 包含 API 密钥的环境变量名称运行器可以在统一接口背后驱动三种 SDK:
openai_agents(默认)— OpenAI Agents Python SDK。支持
多角色交接、chat_completions 和 responses 两种
api_type、temperature、parallel_tool_calls、
exclude_from_context,以及基于 stdio、SSE 和可流式 HTTP 的 MCP。copilot_sdk — GitHub Copilot Python SDK。支持流式传输、
reasoning_effort、基于 stdio/SSE/HTTP 的 MCP,以及按工具权限
门控。该 SDK 会为每个模型自行选择线路协议,因此 YAML 中的
api_type 字段不会被采用;多角色交接、
temperature 和 parallel_tool_calls 同样不可用。
使用不受支持字段的任务流会在加载时失败,并抛出
BackendCapabilityError,指明有问题的字段。anthropic_sdk — Anthropic Python SDK,驱动原生
Messages API(/v1/messages)。支持流式传输、通过
MCP 进行工具调用,以及带有可配置 reasoning.effort
(low、medium、high、max)的自适应思考。不支持交接。
设计用于 CAPI 的 Anthropic 端点;认证使用
Authorization: Bearer(而非 x-api-key)。选择优先级(从高到低):
model_settings 块中的按任务 backend:(针对该单个任务覆盖
模型级值;参见 _resolve_task_model())。model_settings 中的按模型 backend:(允许
在单个任务流中混合使用后端)。backend: 字段
(全局默认值)。SECLAB_TASKFLOW_BACKEND 环境变量。openai_agents。seclab-taskflow-agent:
version: "1.0"
filetype: model_config
models:
code_analysis: claude-opus-4.7
general_tasks: gpt-5.4-mini
model_settings:
code_analysis:
api_type: messages
backend: anthropic_sdk
reasoning:
effort: high
general_tasks:
api_type: responses
backend: openai_agents
每个后端适配器都会将其 SDK 原生异常转换为 sdk/errors.py 中的中立层级,因此运行器无需导入任何 SDK 即可应用重试策略。添加后端意味着也要转换其错误;test_every_backend_adapter_translates_transport_failures 会在整个注册表中强制执行这一点。
传输故障需要显式处理,且很容易被遗漏。厂商 SDK 仅在发送请求的调用周围包装 httpx,而在流式传输下,该调用在响应头到达时即返回,响应体随后才被迭代。因此,若连接在响应体传输中途断开,会表现为一个裸 httpx 错误,既不属于 SDK 自身的层级,也不属于内置异常层级。sdk/_transport.py 枚举了可重试的异常,每个适配器将它们映射为 BackendTransportError。该集合是逐一枚举的,而非整体捕获 httpx.TransportError,因为 LocalProtocolError 表示请求格式错误,而 UnsupportedProtocol 是确定性的。
重试只有一个归属者:_deploy_with_transport_retry 中的分支。它是唯一在两次尝试之间重置捕获状态的层级,因此失败前记录的工具结果不会被发布两次,也不会成为任务的命名输出;并且它只重放失败的那个分支,而非可能已写入外部系统的同级分支。重试受 TASK_RETRY_LIMIT 限制,并采用从 TASK_RETRY_BACKOFF 开始的线性退避。
其上层或下层都不会对相同的异常类进行重试。重试循环会嵌套,因此若某个异常类在两个层级都被捕获,尝试次数会相乘而非相加,且每次尝试都会重放整个对话。drive_backend_stream 仅重试 BackendRateLimitError,此时尚未输出任何内容,并接受一个 reset_capture 回调,因此即使该路径也不会留下部分尝试的结果。
确定性故障完全不重试。BackendMaxTurnsError、BackendBadRequestError 和 BackendCapabilityError 若重试只会以退避方式重复相同的失败,因此 deploy_task_agents 会报告它们并返回。
Taskflow 运行会在任务级别自动创建检查点。如果任务在耗尽重试后失败,会话会被保存并可恢复:
** 🤖💾 Session saved: abc123def456
** 🤖💡 Resume with: --resume abc123def456
从上一个成功的检查点继续:
python -m seclab_taskflow_agent --resume abc123def456
会话检查点会持久化 CLI 提供的 --model-config 值(如果有),因此恢复时默认使用相同的模型配置。要在恢复时覆盖模型配置,请显式传入 --model-config / -m:
python -m seclab_taskflow_agent --resume abc123def456 -m examples.model_configs.responses_api
失败的任务会自动重试,最多重试 3 次,且每次重试的退避时间递增,之后才会保存会话。会话检查点存储在平台特定的应用程序数据目录中。
每次运行都会生成一份机器可读的清单,汇总本次运行的情况:每个任务的状态(ok / failed / skipped)、每个任务所针对的模型、耗时,以及每个任务产生的具名 outputs(包括多模型任务的按模型扇入记录)。清单中不包含端点或令牌。
当运行完成或失败时,清单会被写入运行范围内的 artifacts 目录,并且可以通过会话 ID 为任意会话打印清单:
python -m seclab_taskflow_agent --manifest abc123def456
默认情况下,错误以简洁的单行消息显示。使用 --debug(或设置 TASK_AGENT_DEBUG=1)可查看完整回溯:
# Concise (default)
Error: [BadRequestError] model 'foo' not found
(use --debug for full traceback)
# Full traceback
python -m seclab_taskflow_agent --debug -t examples.taskflows.echo
任务流可以通过 --lint 进行离线验证,无需进行任何模型调用。该选项会解析任务流及其引用的每一个文档(人格、工具箱、模型配置、可复用任务流),对照模型配置检查模型名称,验证提示词/over 模板语法,并报告未知字段(很可能是拼写错误):
# Validate a taskflow and its references
python -m seclab_taskflow_agent --lint -t examples.taskflows.echo
# Treat unknown fields as errors (not just warnings)
python -m seclab_taskflow_agent --lint --strict -t examples.taskflows.echo
--lint 在发现任何错误时会以非零状态退出,因此可用于 CI 门禁。每种语法文档类型的 JSON Schema 可通过 --schema 打印,用于编辑器集成和外部验证:
python -m seclab_taskflow_agent --schema
默认情况下,MCP 服务器子进程会继承父进程的环境变量。为防止特定变量泄露给 MCP 服务器,请将 TASKFLOW_ENV_DENYLIST 设置为以逗号分隔的变量名列表:
export TASKFLOW_ENV_DENYLIST="MY_SECRET_TOKEN,PRIVATE_KEY,OTHER_CREDENTIAL"
YAML 中工具级别的 env: 声明仍会精确注入每个服务器所需的内容,因此显式配置的变量不受影响。
Seclab Taskflow Agent 框架主要设计用于契合 Agentic 安全研究工作流和漏洞分类任务中所涉及的迭代反馈循环驱动型工作。
其设计理念的核心在于:随着前沿模型能力的不断演进,在提示词层面聚焦于捕获漏洞模式,将大幅提升并扩展安全研究的成果。
在 GitHub Security Lab,我们主要将该框架用作代码审计工具,但它也可以作为探索 Agentic 工作流的更通用的瑞士军刀。例如,我们还使用该框架进行自动化代码扫描告警分类。