Agente de Taskflow do GitHub Security Lab

O Agente de Taskflow do Security Lab é uma estrutura multiagente com suporte a MCP para fluxos de trabalho agênticos declarativos, orientados por YAML.

Construído sobre o OpenAI Agents SDK, utiliza Pydantic para validação de gramática e Jinja2 para renderização de templates.

Conceitos Fundamentais

O Agente de Taskflow utiliza uma gramática baseada em YAML semelhante à do GitHub Workflow para executar uma série de tarefas usando um conjunto de Agentes.

A sua principal proposta de valor é ser uma ferramenta CLI que permite aos utilizadores definir e criar scripts de fluxos de trabalho agênticos rapidamente, sem terem de escrever qualquer código.

Os Agentes são definidos através de personalidades, que recebem uma tarefa para completar, dado um conjunto de ferramentas.

Os Agentes podem cooperar para completar sequências de tarefas através dos chamados taskflows.

Pode encontrar uma visão geral detalhada da gramática de taskflow aqui e exemplos de taskflows aqui.

Arquitetura

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

Tipos de API

O agente suporta tanto a API Chat Completions quanto a Responses da OpenAI. O tipo de API pode ser configurado globalmente ou por modelo em um arquivo 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 por modelo pode incluir:

api_type — "chat_completions" (padrão) ou "responses"
endpoint — substituição da URL base da API para este modelo
token — nome de uma variável de ambiente que contém a chave da API

Backends

O runner pode operar três SDKs por trás de uma interface comum:

openai_agents (padrão) — o OpenAI Agents Python SDK. Suporta handoffs multi-personalidade, tanto chat_completions quanto responses api_type, temperature, parallel_tool_calls, exclude_from_context, e MCP sobre stdio, SSE e streamable HTTP.
copilot_sdk — o GitHub Copilot Python SDK. Suporta streaming, reasoning_effort, MCP sobre stdio/SSE/HTTP, e controle de permissão por ferramenta. O SDK seleciona seu próprio protocolo de comunicação por modelo, então o campo api_type do YAML não é respeitado; handoffs multi-personalidade, temperature e parallel_tool_calls também não estão disponíveis. Taskflows que usam campos não suportados falham no carregamento com um BackendCapabilityError nomeando o campo infrator.
anthropic_sdk — o Anthropic Python SDK, operando a API nativa Messages (/v1/messages). Suporta streaming, chamada de ferramentas via MCP, e pensamento adaptativo com reasoning.effort configurável (low, medium, high, max). Handoffs não são suportados. Projetado para uso com o endpoint Anthropic da CAPI; a autenticação usa Authorization: Bearer (não x-api-key).

Precedência de seleção (da maior para a menor):

backend: por tarefa no bloco model_settings da própria tarefa (sobrepõe o valor em nível de modelo para aquela tarefa específica; veja _resolve_task_model()).
backend: por modelo no model_settings da configuração do modelo (permite backends mistos em um único taskflow).
Campo backend: no nível superior do documento de configuração do modelo (padrão global).
Variável de ambiente 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

Recuperação de Sessão

As execuções do Taskflow são automaticamente checkpointadas no nível da tarefa. Se uma tarefa falhar após esgotar as tentativas, a sessão é salva e pode ser retomada:

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

Retome a partir do último checkpoint bem-sucedido:

python -m seclab_taskflow_agent --resume abc123def456

O checkpoint de sessão persiste o valor de --model-config fornecido pela CLI (se houver), portanto os resumes usam a mesma configuração de modelo por padrão. Para substituir a configuração de modelo no resume, passe --model-config / -m explicitamente:

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

Tarefas com falha são automaticamente repetidas até 3 vezes com backoff crescente antes que a sessão seja salva. Os checkpoints de sessão são armazenados no diretório de dados da aplicação específico da plataforma.

Manifesto de Execução

Cada execução produz um manifesto legível por máquina que resume o que aconteceu: status por tarefa (ok / failed / skipped), os modelos com os quais cada tarefa foi executada, o tempo, e os outputs nomeados que cada tarefa produziu (incluindo registros de fan-in por modelo para tarefas multi-modelo). Não contém endpoints nem tokens.

O manifesto é gravado num diretório de artefactos com âmbito de execução quando uma execução termina ou falha, e pode ser impresso para qualquer sessão por ID:

python -m seclab_taskflow_agent --manifest abc123def456

seclab-taskflow-agent

Mais Populares