{"id":50535296,"url":"https://github.com/jcmdsbr/poc-workflow-agentic-squad-agile","last_synced_at":"2026-06-03T16:01:15.506Z","repository":{"id":350451739,"uuid":"1206441999","full_name":"jcmdsbr/poc-workflow-agentic-squad-agile","owner":"jcmdsbr","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-10T12:07:45.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T13:18:47.721Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcmdsbr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T23:23:34.000Z","updated_at":"2026-04-10T11:37:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jcmdsbr/poc-workflow-agentic-squad-agile","commit_stats":null,"previous_names":["jcmdsbr/poc-workflow-agentic-squad-agile"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jcmdsbr/poc-workflow-agentic-squad-agile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmdsbr%2Fpoc-workflow-agentic-squad-agile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmdsbr%2Fpoc-workflow-agentic-squad-agile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmdsbr%2Fpoc-workflow-agentic-squad-agile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmdsbr%2Fpoc-workflow-agentic-squad-agile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcmdsbr","download_url":"https://codeload.github.com/jcmdsbr/poc-workflow-agentic-squad-agile/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmdsbr%2Fpoc-workflow-agentic-squad-agile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33872298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T16:01:14.313Z","updated_at":"2026-06-03T16:01:15.501Z","avatar_url":"https://github.com/jcmdsbr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# poc-agent — Pipeline Multi-Agente para Azure DevOps\n\nPipeline automatizado que lê uma **especificação funcional** e cria, no Azure DevOps, a hierarquia completa de **Features → User Stories → Tasks** usando agentes de IA especializados com [LangChain](https://python.langchain.com/).\n\n## Como Funciona\n\nA ideia é simples: você escreve uma spec funcional (Markdown) e o pipeline a transforma numa hierarquia de trabalho pronta no Azure DevOps, sem intervenção manual.\n\nQuatro agentes executam em sequência, cada um recebendo o resultado do anterior:\n\n```\nEspecificação (.md)\n        │\n        ▼\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│     Bic       │     │     Mimi      │     │   Givaldo     │     │   Jaiminho    │\n│  Arquiteto    │────▶│ Product Owner │────▶│  Tech Lead    │────▶│ Desenvolvedor │\n│  (análise)    │     │  (Features)   │     │(User Stories) │     │   (Tasks)     │\n└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘\n                            │                    │                    │\n                            ▼                    ▼                    ▼\n                     ┌─────────────────────────────────────────────────────┐\n                     │              Azure DevOps (REST API)                │\n                     │    Features ← User Stories ← Tasks (hierárquico)   │\n                     └─────────────────────────────────────────────────────┘\n```\n\n### Os Agentes\n\n| Agente | Papel | O que produz |\n|--------|-------|--------------|\n| **Bic** | Arquiteto .NET Sênior | Documento de arquitetura em Markdown — complementa a spec com observabilidade, resiliência, segurança e mensageria |\n| **Mimi** | Product Owner | 2-3 Features no Azure DevOps representando processos de negócio (nunca componentes técnicos) |\n| **Givaldo** | Tech Lead | Até 5 User Stories por Feature, com contrato de API REST ou CloudEvents e critérios de aceite Gherkin |\n| **Jaiminho** | Desenvolvedor .NET Sênior | Exatamente 4 Tasks por User Story: Análise, Desenvolvimento, Integração/Testes e Testes de Unidade |\n\n---\n\n## Decisão Técnica: Por que LangChain?\n\nEsta POC foi construída em três iterações, cada uma com um framework diferente. O resumo:\n\n### Iteração 1 — CrewAI\n\nO projeto começou com [CrewAI](https://docs.crewai.com/), que oferece uma abstração de alto nível (Crew, Agent, Task) com orquestração declarativa.\n\n**Problemas encontrados:**\n\n- O CrewAI injeta cabeçalhos proprietários nas chamadas ao LLM, o que **aumentou significativamente a taxa de erros 503 / RESOURCE_EXHAUSTED** no Gemini (o provider usado nesta POC)\n\n- Pouco controle sobre o loop interno do agente — difícil ajustar o comportamento quando o modelo começa a alucinar `parent_id`\n- Abstração pesada: ao depurar, era difícil saber exatamente qual chamada estava falhando\n- Dependência de `CREWAI_TRACING_ENABLED=false` para não vazar dados para servidores externos\n\n### Iteração 2 — LangGraph\n\n[LangGraph](https://langchain-ai.github.io/langgraph/) modela o workflow como um **grafo de estados** (`StateGraph`), com nós, arestas e checkpoints.\n\n**Por que não foi adotado:**\n\n- Para um pipeline **puramente sequencial** (sem ciclos, sem branches condicionais), o grafo é over-engineering — exige definir `TypedDict` de estado, registrar cada nó e conectá-los com `add_edge`\n- O valor do LangGraph aparece em cenários mais complexos: retry de nó individual, paralelismo, loops de reflexão. Esse pipeline não tem nenhum desses requisitos\n- Mais código boilerplate para o mesmo resultado\n\n\u003e LangGraph seria a escolha certa se o pipeline precisasse de: retomar do ponto de falha sem reiniciar tudo, paralelizar criação de Features/Stories/Tasks, ou adicionar um agente de revisão com retorno condicional.\n\n### Iteração 3 — LangChain (escolha final)\n\nLangChain puro (sem o grafo) resolveu os problemas anteriores:\n\n| Critério | Resultado |\n|----------|-----------|\n| **Erros 503** | Reduzidos — sem cabeçalhos extras, as chamadas chegam mais \"limpas\" ao Gemini |\n| **Controle do loop** | `AgentExecutor` com `max_iterations` explícito por agente |\n| **Legibilidade** | Agentes simples usam LCEL (`prompt \\| llm \\| parser`); agentes com tools usam `create_tool_calling_agent` |\n| **Código** | Cada agente tem ~30 linhas: system prompt, task template, factory de 1 linha |\n| **Sem lock-in** | Trocar o LLM é mudar uma variável de ambiente |\n\nO pipeline sequencial é orquestrado diretamente em Python, em [workflow.py](workflow.py) — sem framework de orquestração. O que você vê é o que acontece.\n\n---\n\n## Estrutura do Projeto\n\n```\n├── config.py          # LLM factory com rate limiter, retry e fallback\n├── tools.py           # Tool Azure DevOps + WorkItemRegistry (anti-hallucination de IDs)\n├── workflow.py        # Orquestrador: chama os agentes em sequência\n├── agents/\n│   ├── _base.py       # Classe Agent + helper make_tool_agent (elimina boilerplate)\n│   ├── bic.py         # Agente Arquiteto (LCEL puro, sem tools)\n│   ├── mimi.py        # Agente Product Owner (tool-calling)\n│   ├── givaldo.py     # Agente Tech Lead (tool-calling)\n│   └── jaiminho.py    # Agente Desenvolvedor (tool-calling)\n├── specs/\n│   └── exemplo_estorno.md  # Exemplo de especificação funcional\n├── .env.example       # Template de variáveis de ambiente\n├── requirements.txt   # Dependências Python\n└── Dockerfile         # Imagem para execução containerizada\n```\n\n---\n\n## Pré-requisitos\n\n- Python 3.11+\n- Azure DevOps com Personal Access Token (PAT) com permissão de escrita em Work Items\n- Chave de API do **Google Gemini** (ou adapte `config.py` para outro provider)\n\n## Configuração\n\n1. Clone o repositório:\n\n```bash\ngit clone \u003curl-do-repositório\u003e\ncd poc-agent\n```\n\n2. Crie o ambiente virtual e instale as dependências:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n3. Copie e preencha o arquivo de configuração:\n\n```bash\ncp .env.example .env\n```\n\n4. Edite o `.env` com suas credenciais:\n\n```env\n# Azure DevOps (obrigatório)\nAZURE_ORG=sua-organizacao\nAZURE_PROJECT=seu-projeto\nAZURE_PAT=seu-personal-access-token\n\n# LLM (obrigatório)\nGEMINI_API_KEY=sua-chave\nLLM_MODEL=gemini-2.5-flash\n\n# Opcional: modelo de fallback caso o primário retorne 503 repetidamente\n# LLM_FALLBACK_MODEL=gemini-2.0-flash\n```\n\n## Execução\n\n```bash\n# Passando a especificação como arquivo\npython workflow.py specs/exemplo_estorno.md\n\n# Ou via stdin\ncat especificacao.md | python workflow.py\n```\n\n### Docker\n\n```bash\ndocker build -t poc-agent .\ndocker run --env-file .env -v ./especificacao.md:/app/especificacao.md poc-agent python workflow.py especificacao.md\n```\n\n---\n\n## Detalhes de Implementação\n\n### Pipeline Sequencial (`workflow.py`)\n\nQuatro chamadas encadeadas em Python puro:\n\n```python\narch_output     = generate_architecture(bic, specification)   # Bic: análise técnica\nfeatures_output = create_features(mimi, arch_output)          # Mimi: Features no DevOps\nstories_output  = create_stories(givaldo, features_output, specification)  # Givaldo: User Stories\ntasks_output    = create_tasks(jaiminho, stories_output, specification)    # Jaiminho: Tasks\n```\n\nCada função recebe o output da etapa anterior — sem framework de orquestração, sem magia.\n\n### Dois padrões de agente (`agents/`)\n\n**Agente simples (Bic)** — usa LCEL, sem tools, sem loop:\n```python\nchain = prompt | llm | StrOutputParser()\n```\n\n**Agente com tool-calling (Mimi, Givaldo, Jaiminho)** — usa `AgentExecutor` com loop ReAct:\n```python\n# make_tool_agent em _base.py centraliza esse padrão para os 3 agentes\nreturn make_tool_agent(\"Mimi — Product Owner\", llm, tool, _SYSTEM, max_iterations=15)\n```\n\n### Anti-hallucination de IDs (`tools.py`)\n\nO LLM tende a inventar `parent_id`. O `WorkItemRegistry` resolve isso:\n\n- Registra cada Work Item criado com seu ID real\n- Quando um agente tenta criar um filho, valida se o `parent_id` existe e é do tipo correto\n- Se inválido, retorna a lista de IDs válidos para o agente se corrigir na próxima iteração\n\n```\nFeature       → sem pai\nUser Story    → pai deve ser Feature\nTask          → pai deve ser User Story\n```\n\n### Rate limiting e retry (`config.py`)\n\nO `_ThrottledLLM` é um wrapper sobre o LLM que:\n- Controla requisições por minuto (janela deslizante de 60s)\n- Retry com backoff exponencial para erros 503/429\n- Fallback automático para um modelo alternativo após N tentativas falhas\n\n### Normalização de Input (`WorkItemInput`)\n\nO LLM pode enviar campos em diferentes formatos (`titulo`, `Titulo`, `title`, `Title`...). O `model_validator` no Pydantic normaliza tudo antes de chamar a API do Azure DevOps.\n\n---\n\n## Configurações Avançadas\n\n| Variável | Padrão | Descrição |\n|----------|--------|-----------|\n| `LLM_MODEL` | `gemini-2.5-flash` | Modelo principal |\n| `LLM_FALLBACK_MODEL` | _(vazio)_ | Modelo alternativo ativado após `LLM_FALLBACK_AFTER` erros 503 |\n| `LLM_FALLBACK_AFTER` | `3` | Tentativas antes de acionar o fallback |\n| `LLM_RPM` | `10` | Requests por minuto |\n| `LLM_MAX_RETRIES` | `8` | Tentativas totais por chamada |\n| `LLM_RETRY_BASE_DELAY` | `15` | Delay base em segundos (backoff exponencial) |\n| `LLM_RETRY_MAX_DELAY` | `120` | Teto do backoff em segundos |\n| `LOG_LEVEL` | `INFO` | Nível de log (`DEBUG` para ver payloads completos) |\n\n---\n\n## Licença\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcmdsbr%2Fpoc-workflow-agentic-squad-agile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcmdsbr%2Fpoc-workflow-agentic-squad-agile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcmdsbr%2Fpoc-workflow-agentic-squad-agile/lists"}