CodeQL 통합과 함께 AI 지원 코드 감사, 취약점 분류 및 보안 연구에 사용되는 선언적 YAML 기반 에이전트 워크플로를 위한 MCP 지원 멀티 에이전트 프레임워크입니다.
Security Lab Taskflow Agent는 선언적이고 YAML 기반의 에이전트 워크플로를 위한 MCP 지원 멀티 에이전트 프레임워크입니다.
OpenAI Agents SDK를 기반으로 구축되었으며, 문법 검증에는 Pydantic을, 템플릿 렌더링에는 Jinja2를 사용합니다.
Taskflow Agent는 GitHub Workflow와 유사한 YAML 기반 문법을 활용하여 일련의 에이전트들을 통해 일련의 작업을 수행합니다.
주요 가치 제안은 사용자가 코드를 작성할 필요 없이 에이전트 워크플로를 신속하게 정의하고 스크립트화할 수 있게 해주는 CLI 도구라는 점입니다.
에이전트는 personalities를 통해 정의되며, 일련의 tools가 주어진 상태에서 완료할 task를 받습니다.
에이전트는 소위 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
에이전트는 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 엔드포인트와 함께 사용하도록 설계되었으며, 인증에는 x-api-key가 아닌 Authorization: Bearer를 사용합니다.선택 우선순위(높은 순에서 낮은 순):
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를 감싸며, 스트리밍의 경우 응답 헤더가
도착하면 반환되고 본문은 그 이후에 반복 처리됩니다. 따라서 본문 도중에
끊긴 연결은 SDK 자체의 계층 구조에도, 내장 예외에도 속하지 않는 순수한
httpx 오류로 나타납니다. 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(다중 모델 작업의 경우 모델별 팬인 기록 포함). 여기에는 엔드포인트나 토큰이 포함되지 않습니다.
매니페스트는 실행이 완료되거나 실패할 때 실행 범위 아티팩트 디렉터리에 기록되며, 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 템플릿 구문을 검증하고,
알 수 없는 필드(오타 가능성이 높음)를 보고합니다: