GitHub Security Lab Taskflow Agent

Security Lab Taskflow Agent 是一个支持 MCP 的多 Agent 框架，用于声明式、YAML 驱动的智能体工作流。

它构建于 OpenAI Agents SDK 之上，使用 Pydantic 进行语法验证，并使用 Jinja2 进行模板渲染。

核心概念

Taskflow Agent 利用类似 GitHub Workflow 的基于 YAML 的语法，使用一组 Agent 来执行一系列任务。

它的主要价值定位是作为一个 CLI 工具，允许用户快速定义和编写智能体工作流脚本，而无需编写任何代码。

Agent 通过 personalities 定义，它们接收一个 task 来完成，并给定一组 tools。

Agent 可以通过所谓的 taskflows 协作完成一系列任务。

你可以在此处找到 taskflow 语法的详细概述 here，以及示例 taskflows here。

架构

┌─────────────────────────────────────────────────────┐
│                   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

API 类型

该 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）。

选择优先级（从高到低）：

1. 任务自身 model_settings 块中的按任务 backend:（针对该单个任务 覆盖模型级值；参见 _resolve_task_model()）。
2. 模型配置的 model_settings 中的按模型 backend:（允许 在单个任务流中混合后端）。
3. 模型配置文档顶层的 backend: 字段 （全局默认）。
4. SECLAB_TASKFLOW_BACKEND 环境变量。
5. 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

会话恢复

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

代码检查与模式验证

Taskflows 可以在不进行任何模型调用的情况下离线验证，使用 --lint。这会解析 taskflow 及其引用的每个文档 （personalities、toolboxes、model configs、可复用的 taskflows），根据模型配置检查模型 名称，验证 prompt/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 服务器子进程会继承父进程的环境变量。为防止特定变量泄露给 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 工作流的更通用的瑞士军刀。例如，我们也使用该框架进行自动化代码扫描告警分类。

该框架包含一个 CodeQL MCP 服务器，可用于 Agentic 代码审查，参见 CVE-2023-2283 taskflow，了解如何让 Agent 使用 CodeQL 数据库审查 C 代码的示例（演示视频）。

CodeQL MCP 服务器并非自行生成 CodeQL 查询，而是用于提供基于 CodeQL 查询的 MCP 工具，使 Agent 能够导航和探索代码。它利用模板化的 CodeQL 查询，为模型驱动的代码分析提供有针对性的上下文。

模型比较与评估

该框架还可以在多个模型上运行相同的提示词并比较它们的回答，这对于在给定任务上评估模型之间的表现非常有用。example_model_comparison taskflow 展示了这一模式：一个多模型任务将同一个问题分发到两个模型，使用 capture: response 捕获每个模型的文字回答，然后第二个“评判”任务按名称读取每个捕获的回答（outputs.answers）并选出最佳的一个。

像运行任何其他 taskflow 一样，针对你的端点运行它：

python -m seclab_taskflow_agent -t examples.taskflows.example_model_comparison

每个模型在其各自带标签的输出块中作答，然后评判任务对它们进行比较，例如：