Guia de engenharia — Agentes de IA no agno

Crie um agente quando a tarefa exige decisão ou linguagem natural que depende de um LLM: classificar, resumir, redigir, conversar, validar conteúdo, extrair dados de texto livre.

Se a tarefa é determinística (mover status, calcular prazo, disparar webhook), não é agente — é automação comum no backend. Todo agente é advisory: sugere, o advogado decide.

Referência: apps/agno/pre_kickoff/route.py. Ordem do route.py:

• _SYSTEM_BASE — a constante do prompt
• Request(BaseModel) — Pydantic do request
• _verify_bearer(request) — auth por AGNO_API_KEY
• _build_system(...) — monta o system prompt com contexto do caso
• _complete(...) — a única função que fala com o LLM (é o que os testes mockam)
• register(app) — declara o @app.post("/minha-feature/...")

Wire final em apps/agno/app.py: import minha_feature.route as mf e mf.register(app).

Pipeline rico (ferramentas externas, dry-run, RAG, persistência): siga apps/agno/intake/ (route → pipeline → llm → schema → data → rag).

• Scoping: case_id (int) é a chave para agentes que atuam sobre um caso.
• Auth: Bearer AGNO_API_KEY (helper _verify_bearer; no-op se a env não estiver setada).
• Saída: sempre inclua o disclaimer de revisão do advogado quando a resposta for de IA.

Exemplo real: POST /pre-kickoff/draft-message in {case_id, client_name?, case_type?} → out {message}.

Escrita (intake/rag.py): embeddings text-embedding-3-small (1536 dims), upsert idempotente por (case_id, source_type) em case_knowledge_chunks.

Leitura: injeta os últimos N chunks no system prompt. O source_type é o que a Base de conhecimento do Caso (aba Geral) agrupa e mostra ao time — escolha um claro.

O frontend nunca fala com o agno direto: passa pelo apps/backend. Padrão:

• Router com requireIdentity (JWT do caller); escrita/sandbox também com requireCoordinator.
• Factory testável createXHandler({ supabase, agnoBaseUrl, agnoToken, fetch }).
• Enriquece do Supabase → fetch no agno com Bearer → 502 em falha.
• Persiste turnos quando é conversa (case_agent_messages). Mount em server.mjs.

Convenção atual: novos routers em apps/backend/src/routes/ (ex.: agents-pre-kickoff.mjs).

apps/agno/tests/ com pytest: cria FastAPI() isolado, chama register(app), TestClient, e patch("...route._complete", return_value=...) para o LLM nunca rodar.

Obrigatório: teste de contrato (mockando _complete) + teste de não-vazamento de PII em log. No espelho Node, testar a factory com fetch fake.

agno: DATABASE_URL, OPENROUTER_API_KEY, AGNO_DEFAULT_MODEL, AGNO_API_KEY, CORS_ALLOWED_ORIGINS, PORT (8000).

backend Node: AGNO_BASE_URL / AGNO_URL (default http://localhost:8000).

• COMP-04 — nunca logar/indexar PII crua; só resumo no RAG. Com teste que prova.
• COMP-06 — saída sempre com disclaimer "Documento sujeito à revisão do advogado responsável"; agente sugere, não decide.
• COMP-05 — se talks_to_client=true, PT-BR claro.

📄 "Doc feedback APP" (estilo B)

Quando um documento chega pelo APP, o agente revisa e gera o feedback estruturado. Consumidor visível: document.html.

POST /documents/review
in:  { case_id, document_id, document_type_expected?, file_ref }
out: { verdict: "ok"|"ressalva"|"rejeitado",
       checks: [ { name, pass, note } ],
       summary, attorney_review_required: true, disclaimer }

Checks v1: tipo confere · legível · completo · assinado/datado. O summary vira o card "Doc feedback APP"; o verdict dirige o stepper.

RAG: indexa só o summary com source_type='document_review'.

Fora do escopo v1 (vira tarefa futura): OCR/leitura do arquivo, classificação multi-tipo, extração de campos. Detalhe completo em specs/Yousa Agno/Conhecimento e Memoria/Tarefas/24-guia-agentes-ia-agno/exemplo-doc-feedback-app.md.