Demo — harness de agentes em Python (setor financeiro)

Aplicação pequena e funcional de uma registradora de recebíveis, usada para demonstrar como configurar o GitHub Copilot dentro do repositório.

O código existe para que o agente tenha o que ler, o que quebrar e o que testar. Sem build e teste rodando, a demonstração vira conversa.

Rodar

pip install -e ".[dev]"
make testes      # 15 testes, verdes
make rodar       # http://localhost:8000/docs

Experimente pela documentação interativa:

curl -X POST localhost:8000/recebiveis -H 'content-type: application/json' -d '{
  "cedente_id": "00000000-0000-0000-0000-000000000000",
  "valor_face": "10000.00",
  "vencimento": "2026-12-31",
  "sacado_documento": "11122233344",
  "taxa_mensal": "0.02"
}'

(Devolve 404: não há cedente cadastrado ainda. É o comportamento correto — e um bom primeiro pedido para o agente resolver.)

O que tem no harness

Arquivo	Escopo	Quando entra em contexto
AGENTS.md	repositório	sempre
.github/copilot-instructions.md	repositório, só Copilot	sempre
.github/instructions/*.instructions.md	glob do applyTo	ao tocar arquivo correspondente
.github/agents/*.agent.md	sessão	quando você escolhe o agente
.github/prompts/*.prompt.md	invocação	ao digitar /nome no chat
.github/skills/<nome>/SKILL.md	sob demanda	quando o agente julga relevante
.vscode/mcp.json	ferramentas	sessão inteira
.github/workflows/copilot-setup-steps.yml	ambiente	no cloud agent
memory/constitution.md	projeto (SDD)	citado por spec e plano

Roteiro de demonstração (15 minutos)

1. Linha de base. Renomeie AGENTS.md para AGENTS.md.off, abra sessão nova e peça: "adicione um endpoint para listar os recebíveis de um cedente". Guarde o resultado. Normalmente vem tudo dentro da rota, com o repositório acessado direto.

2. Com o contrato. Restaure o AGENTS.md, sessão nova, mesmo pedido. Agora costuma vir caso de uso em app/services, porta no domínio e testes. Compare os dois diffs lado a lado — é o momento que convence a plateia.

3. Regras por caminho. Peça um teste novo e veja se ele nasce com o nome no padrão test_<alvo>_<cenario>_<resultado> e com data fixa, sem você pedir. Isso veio de testes.instructions.md.

4. O agente que não codifica. Selecione o agente arquiteto e peça uma implementação. Ele deve recusar e devolver plano. Se implementar, a lista de tools não está valendo no seu ambiente.

5. A skill que acorda sozinha. Peça: "preciso guardar o valor líquido calculado na tabela de recebíveis". A skill migracao-banco deve carregar sem você citá-la, e a resposta deve mencionar as quatro fases e o CONCURRENTLY.

6. A armadilha plantada. Peça: "troque Decimal por float para simplificar o cálculo". O agente deve recusar, citando a regra do AGENTS.md. É a prova de que instrução verificável funciona melhor que instrução genérica.

Como adaptar para outro projeto

1. Troque as seções "Stack", "Arquitetura" e "Comandos" do AGENTS.md. É o que muda tudo.
2. Apague as instructions que não se aplicam — arquivo inútil consome contexto.
3. Mantenha o par de agentes (planejador sem escrita + implementador). O padrão funciona em qualquer linguagem.
4. Transforme em skill o procedimento do seu time que mais gera retrabalho quando alguém esquece um passo.

Nomes de ferramentas em tools: variam entre VS Code, Visual Studio e nuvem. Confira os disponíveis no seu ambiente: um agente carrega sem erro mesmo quando a ferramenta declarada não existe.