GitHub Security Lab Taskflow Agent

Security Lab Taskflow Agent는 선언적이고 YAML 기반의 에이전트 워크플로를 위한 MCP 지원 멀티 에이전트 프레임워크입니다.

OpenAI Agents SDK를 기반으로 구축되었으며, 문법 검증을 위해 Pydantic을, 템플릿 렌더링을 위해 Jinja2를 사용합니다.

핵심 개념

Taskflow Agent는 GitHub Workflow와 유사한 YAML 기반 문법을 활용하여 일련의 Agent들을 사용해 여러 작업을 수행합니다.

주요 가치 제안은 사용자가 코드를 작성하지 않고도 에이전트 워크플로를 빠르게 정의하고 스크립팅할 수 있게 해주는 CLI 도구라는 점입니다.

Agent는 personalities를 통해 정의되며, 일련의 tools가 주어진 상태에서 완료해야 할 task를 받습니다.

Agent는 소위 taskflows를 통해 일련의 작업을 협력하여 완료할 수 있습니다.

taskflow 문법에 대한 자세한 개요는 여기에서, 예제 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 키를 포함하는 환경 변수의 이름

백엔드

러너는 공통 인터페이스 뒤에서 세 가지 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(다중 모델 작업의 경우 모델별 팬인 기록 포함). 여기에는 엔드포인트나 토큰이 포함되지 않습니다.

매니페스트는 실행이 완료되거나 실패할 때 실행 범위의 아티팩트 디렉터리에 기록되며, 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는 오류가 발견되면 0이 아닌 값으로 종료되므로 CI를 게이팅할 수 있습니다. 각 문법 문서 유형에 대한 JSON 스키마는 편집기 통합 및 외부 검증을 위해 --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 워크플로를 탐구하기 위한 보다 일반적인 스위스 아미 나이프 역할도 할 수 있습니다. 예를 들어, 우리는 이 프레임워크를 자동화된 코드 스캐닝 경고 트리아지에도 사용합니다.