GitHub Security Lab Taskflow Agent

The Security Lab Taskflow Agent is an MCP-enabled multi-Agent framework for declarative, YAML-driven agentic workflows.

Built on top of the OpenAI Agents SDK, it uses Pydantic for grammar validation and Jinja2 for template rendering.

Core Concepts

The Taskflow Agent leverages a GitHub Workflow-esque YAML based grammar to perform a series of tasks using a set of Agents.

Its primary value proposition is as a CLI tool that allows users to quickly define and script Agentic workflows without having to write any code.

Agents are defined through personalities, that receive a task to complete, given a set of tools.

Agents can cooperate to complete sequences of tasks through so-called taskflows.

You can find a detailed overview of the taskflow grammar here and example taskflows here.

Architecture

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

The agent supports both the Chat Completions and Responses OpenAI APIs. The API type can be configured globally or per model in a model_config file:

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

Per-model model_settings can include:

• api_type — "chat_completions" (default) or "responses"
• endpoint — API base URL override for this model
• token — name of an environment variable containing the API key

Backends

The runner can drive three SDKs behind a common interface:

• openai_agents (default) — the OpenAI Agents Python SDK. Supports multi-personality handoffs, both chat_completions and responses api_type, temperature, parallel_tool_calls, exclude_from_context, and MCP over stdio, SSE, and streamable HTTP.
• copilot_sdk — the GitHub Copilot Python SDK. Supports streaming, reasoning_effort, MCP over stdio/SSE/HTTP, and per-tool permission gating. The SDK selects its own wire protocol per model, so the YAML api_type field is not honoured; multi-personality handoffs, temperature, and parallel_tool_calls are likewise not available. Taskflows that use unsupported fields fail at load time with a BackendCapabilityError naming the offending field.
• anthropic_sdk — the Anthropic Python SDK, driving the native Messages API (/v1/messages). Supports streaming, tool calling via MCP, and adaptive thinking with configurable reasoning.effort (low, medium, high, max). Handoffs are not supported. Designed for use with CAPI's Anthropic endpoint; auth uses Authorization: Bearer (not x-api-key).

Selection precedence (highest to lowest):

1. Per-task backend: in the task's own model_settings block (overrides the model-level value for that one task; see _resolve_task_model()).
2. Per-model backend: in the model config's model_settings (allows mixed backends in a single taskflow).
3. backend: field at the top level of the model config document (global default).
4. SECLAB_TASKFLOW_BACKEND environment variable.
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

Session Recovery

Taskflow runs are automatically checkpointed at the task level. If a task fails after exhausting retries, the session is saved and can be resumed:

** 🤖💾 Session saved: abc123def456
** 🤖💡 Resume with: --resume abc123def456

Resume from the last successful checkpoint:

python -m seclab_taskflow_agent --resume abc123def456

The session checkpoint persists the CLI-provided --model-config value (if any), so resumes use the same model configuration by default. To override the model config on resume, pass --model-config / -m explicitly:

python -m seclab_taskflow_agent --resume abc123def456 -m examples.model_configs.responses_api

Failed tasks are automatically retried up to 3 times with increasing backoff before the session is saved. Session checkpoints are stored in the platform-specific application data directory.

Run Manifest

Every run produces a machine-readable manifest summarising what happened: per-task status (ok / failed / skipped), the models each task ran against, timing, and the named outputs each task produced (including per-model fan-in records for multi-model tasks). It contains no endpoints or tokens.

The manifest is written to a run-scoped artifacts directory when a run finishes or fails, and can be printed for any session by ID:

python -m seclab_taskflow_agent --manifest abc123def456

Error Output

By default, errors are shown as concise one-line messages. Use --debug (or set TASK_AGENT_DEBUG=1) for full tracebacks:

# 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

Linting and Schema