GitHub Security Lab Taskflow Agent

Security Lab Taskflow Agentは、宣言型のYAML駆動エージェントワークフローを実現するMCP対応のマルチエージェントフレームワークです。

OpenAI Agents SDKを基盤とし、文法検証にPydantic、テンプレートレンダリングにJinja2を使用しています。

コアコンセプト

Taskflow Agentは、GitHub Workflow風のYAMLベースの文法を活用し、一連のAgentを用いて一連のタスクを実行します。

その主な価値提案は、コードを一切書くことなく、ユーザーがエージェントワークフローを迅速に定義しスクリプト化できるCLIツールとしての点にあります。

Agentsはpersonalitiesを通じて定義され、一連のtoolsが与えられた上で、完了すべきtaskを受け取ります。

Agentsは、いわゆるtaskflowsを通じて協調し、一連のタスクを完了することができます。

taskflow文法の詳細な概要はこちら、タスクフローの例はこちらで確認できます。

アーキテクチャ

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

エージェントは 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 キーを含む環境変数の名前

バックエンド

ランナーは共通インターフェースの背後で 3 つの 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:（その 1 つのタスクについてモデルレベルの値を上書きします。_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（マルチモデルタスクのモデルごとのファンイン記録を含む）が含まれます。エンドポイントやトークンは含まれません。

マニフェストは、実行が完了または失敗したときに実行スコープのアーティファクトディレクトリに書き込まれ、任意のセッションについてIDで出力できます:

python -m seclab_taskflow_agent --manifest abc123def456

エラー出力

デフォルトでは、エラーは簡潔な1行のメッセージとして表示されます。完全なトレースバックを表示するには、--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 サーバーのサブプロセスは親の環境を継承します。特定の変数が 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 ワークフローを探索するためのより汎用的な万能ナイフとしても機能します。たとえば、自動コードスキャンアラートのトリアージにもこのフレームワークを使用しています。