Entenda o modelo e ponha para rodar.

O que é o Erin

Uma plataforma de trabalho onde parte do time é de agentes de IA. Pessoas preparam e decidem, agentes executam, e cada decisão fica registrada do requisito à entrega.

Pense num quadro de tarefas que você já conhece, com uma diferença: você pode atribuir uma task a uma pessoa ou a um agente, do mesmo jeito. O agente faz o trabalho, um revisor independente julga, e a entrega para num ponto de decisão humana antes de ser aceita. Tudo o que acontece vira um registro que ninguém reescreve.

O Erin se organiza em três camadas: Estrutura (org, times, pessoas e agentes), Trabalho (o quadro) e Execução (o que roda quando uma task cai num agente).

O que dá para fazer

O Erin não é um assistente de chat. Você delega uma unidade de trabalho inteira, com contrato e critério de aceite, e recebe de volta uma entrega com prova. Estes são os recortes que os times rodam hoje.

Uma volta completa, do pedido ao caso dourado

O exemplo abaixo é o formato real de uma volta do Volante. Repare em quem age em cada passo: quando é você, quando é o agente, e o que sobra registrado.

Do zero à primeira entrega

O caminho que todo time percorre. Cada passo é uma tela do produto.

1. Monte a casa.No primeiro acesso, crie o fundador e siga o assistente que monta Org, Workspace, Time e Projeto.
2. Prepare o time.Adicione pessoas com seus papéis e conheça os agentes nativos: Planejador, Pesquisador, Executor e Revisor.
3. Dê conhecimento.Crie ou vincule uma KB de domínio. É o que o agente consulta antes de agir, e cada consulta fica registrada.
4. Crie e refine o trabalho.Épico, história, task. O agente de refino lê a KB e propõe a Spec (o contrato); você aprova no gate.
5. Atribua a um agente.Atribuir é o gatilho de execução. O executor faz, o validador julga em contexto fresco, o loop corrige se preciso.
6. Decida no gate.A entrega espera o seu veredito, com a saída e a prova ao lado. Você aprova ou devolve com orientação.
7. Escale com o Turno da Fábrica.Quando confiar, monte lotes que rodam na janela noturna, com teto de custo. De manhã, os gates esperam por você.

Estrutura e papéis

A hierarquia organiza quem trabalha com o quê: Org contém Workspaces, que contêm Times, que têm Projetos. Pessoas e agentes são membros de um time.

Papéis definem o que cada pessoa pode fazer num workspace. Há presets prontos (Admin, Gestor, Aprovador, Executor, Leitor) e você pode criar os seus. Um papel em uso não some sem antes realocar quem o tem. A permissão de aprovar gates (gate.approve) é o que separa quem decide de quem só acompanha.

O trabalho no quadro

O trabalho vive numa hierarquia: épico, história, task e subtask. Apenas task e subtask são executáveis por um agente; épico e história são contêineres que organizam.

Uma task passa por estados bem definidos: rascunho, pronta, na fila, executando, suspensa, bloqueada por gate e concluída ou falhou. Só transições permitidas acontecem, e mudar de estado no meio da execução é barrado.

Discovery, refino e a Spec

Há dois jeitos de amadurecer o trabalho até ele estar pronto para executar.

Discovery (decompor)

Um épico grande pode ser atribuído a um agente de discovery, que propõe uma árvore de work items. Você revisa no gate de decomposição, edita se quiser, e ao aprovar o sistema materializa os filhos. Prioridade, dependências e critérios propostos são preservados.

Refino (produzir a Spec)

A Spec é o contrato da task concreta: escopo, contratos de saída e critérios de aceite. Um agente de refino consulta a KB e redige a Spec ancorada no domínio. Você aprova no gate. Spec boa é execução confiável: é a tarefa mais importante antes de qualquer agente rodar.

Conhecimento (KB)

O acervo de domínio que o agente consulta antes de agir. É o fosso do produto.

Uma KB é um corpo de documentos estruturados (conceitos, padrões, referências) sobre uma tecnologia ou domínio. KBs nativas são curadas pela casa e compartilhadas; KBs do workspace são suas. Um agente só enxerga as KBs visíveis ao seu tenant.

• Consulta real. Quando o agente consulta a KB, fica registrado qual documento citou, com hash e relevância. É a prova de qual conhecimento embasou a entrega.
• Autoria assistida. Um agente pode redigir os documentos de uma KB a partir de fontes verificáveis, com citação e verificação.
• Publicação e frescor. Uma versão de KB é publicada por aprovação humana e vira um retrato imutável. Conteúdo que envelhece é marcado como desatualizado e barra a publicação até ser revisto.

Agentes

Agentes são membros do time que executam tasks de forma autônoma, sob as suas regras.

Há quatro funções nativas. Cada agente declara comportamento, limites, condições de parada e contrato de saída.

Imutabilidade, versões e promoção

• Nativo é imutável. Para adaptar um agente nativo, você o forka. O original nunca muda.
• Toda mudança cria uma versão. Versão e modelo entram na cadeia. Você vê o histórico e o desempenho de cada versão.
• Promoção com evidência. Uma versão candidata não é despachável. Ela sobe a promovida quando prova valor nos evals e no sinal do gate.
• Composição. A definição de um agente pode declarar os subagentes que ele orquestra (por exemplo, executor e revisor). Chamar o agente já dispara essa composição, de forma determinística.

Provedores e BYOK

Você usa o seu próprio provedor de IA (BYOK, bring your own key). Cada agente define provedor e modelo, com uma cadeia de fallback opcional para falhas de provider.

• Várias conexões (chaves) por provedor, com rótulo amigável. Suporte a Anthropic, OpenAI, Gemini, Groq, DeepSeek, Moonshot, OpenRouter e mais.
• A chave fica no cofre. A interface só recebe uma referência segura, nunca o segredo.
• O custo de inferência fica na sua conta, transparente por agente, modelo e task.

O gatilho único

Existe uma única forma de disparar execução: atribuir uma task a um agente. Não há execução por acaso, por agendamento oculto ou por um agente decidindo rodar sozinho. Isso mantém a operação previsível e auditável.

O motor de execução

Quando uma task cai num agente, um motor determinístico (não um LLM decidindo o control-flow) coordena o ciclo:

1. Executor produz.O agente atribuído faz o trabalho contra a Spec, consultando as KBs vinculadas.
2. Validador julga.Um revisor avalia a saída em contexto fresco, separado de quem produziu. Nunca o executor julgando a si mesmo.
3. Retry corretivo.Se o revisor recusa, o parecer vira o feedback da próxima tentativa. O padrão é 2 tentativas, configurável.
4. Teto de custo.Todo run tem um teto obrigatório. O loop gasta as tentativas até aprovar, estourar o teto ou esgotá-las.
5. Abre o gate.Aprovado internamente, a entrega para no gate e espera a decisão humana.

Gates e decisão

Um gate é um ponto de decisão humana. Abrir um gate pode ser ação de agente ou do sistema; decidir sempre é de um humano com permissão. O agente nunca aprova.

• Evidence Summary. No gate, você vê o resumo verificável do que aconteceu: a saída, a nota do revisor, o custo, as KBs consultadas e a integridade da cadeia. A mesma prova que você baixaria no dossiê completo.
• Maker-checker. Políticas de aprovação por N-de-M e separação de funções podem ser exigidas por workspace. Uma violação vira um registro.
• Efeitos por tipo. Aprovar a Spec deixa a task pronta; aprovar a decomposição materializa os filhos; aprovar a entrega conclui a task. Recusar devolve com orientação para a próxima atribuição.

Turno da Fábrica

Execução em lote e autônoma, para quando você já confia no elenco.

Em vez de atribuir uma task por vez, monte um lote: escolha o projeto, marque as tasks prontas, escolha o agente executor e despache. A execução respeita a janela noturna e os limites que você configurou.

O Volante

O ciclo que faz você confiar mais a cada volta.

Construir fácil, executar bem, decidir com evidência, aprender com golden cases e evals, promover a versão que prova valor, e então confiar e delegar mais. A métrica-norte é a aprovação de primeira: a fração de entregas aprovadas no gate sem retry nem recusa. É ela que mede confiança para delegar em escala.

• Golden cases nascem de decisões de gate boas, colhidas da cadeia. Viram a base de avaliação.
• Evals rodam contra os golden cases. São fail-closed: sem evidência confiável, não inflam a nota.
• Promoção exige evidência. Regressão bloqueia; um override exige justificativa registrada.

A cadeia de auditoria

O substrato que torna o volante honesto.

Toda ação, de humano ou de agente, vira um elo num registro append-only. Os elos são encadeados por hash e a ordem é garantida, então nada é reescrito depois. Golden cases, evals, custo e o scorecard de confiança são todos derivados dela.

• Reproduzível. "Por que decidimos assim?" se responde consultando a cadeia, não escavando históricos soltos.
• Exportável. Você pode exportar a cadeia verificável e um Evidence Pack selado por hash, com spec, gates, atores, versões, refs de KB e custo.
• Íntegra. O servidor recomputa o hash-chain a qualquer momento para provar que nada foi adulterado.

Segurança

• Isolamento por tenant. Um workspace nunca enxerga dados de outro. As tabelas sensíveis têm isolamento em duas camadas.
• Segredos no cofre. A chave BYOK fica cifrada num cofre, nunca em log, banco ou texto puro.
• Registro imutável. A cadeia é protegida contra alteração e remoção no nível do banco, não só na aplicação.
• Escaneamento antes de gravar. O conteúdo é varrido contra vazamento de segredo e PII antes de virar um elo.

Guia: construir um agente

Um agente não é só nome, prompt e modelo. É um contrato de comportamento versionado.

Para criar, comece de um nativo e forke, ou crie do zero. Cada versão declara:

Guia: montar uma KB

Uma KB boa é o que separa um agente que acerta de um que chuta. Este guia monta uma do zero, com o conteúdo real de ponta a ponta.

1. Crie a KB.Dê um slug, a tecnologia e o domínio. Native (compartilhada pela casa, somente leitura) ou do seu workspace.
2. Adicione documentos.Os tipos de conteúdo são concept, pattern, reference e spec. Um index e um quick_reference dão navegação.
3. Escreva a carta.Boundaries, perguntas de discovery e fronteiras de escopo. É o que aparece para você na hora de decidir.
4. Autore com fonte.Para autoria assistida, o agente precisa de um conector de fonte autorizado. O corpo é citado e verificado, nada de memória do modelo solta.
5. Passe os portões de prontidão.Estrutura mínima (index mais concept mais pattern) e cobertura suficiente. A KB fica consultável mesmo incompleta, mas só é publicável quando pronta.
6. Publique.Uma versão é publicada por aprovação humana e vira um retrato imutável. Documento desatualizado barra a publicação.
7. Vincule ao agente.A KB só vira consulta real quando está no binding da versão do agente e a ferramenta de busca está ligada.

Exemplo: a KB "LGPD: Retenção e Expurgo"

Vamos montar uma KB de compliance que um agente de pesquisa vai consultar antes de escrever qualquer Spec sobre dados pessoais.

1. A anatomia. Uma KB é uma árvore de markdown. O diretório define o tipo do documento, então a estrutura já é a taxonomia:

kb_lgpd_retencao/
  index.md                          # navegação: o mapa da KB
  quick-reference.md                # navegação: a cola de consulta rápida
  concepts/
    direito-esquecimento.md         # concept: o que é e por que importa
  patterns/
    expurgo-com-trilha.md           # pattern: como se faz na prática
  reference/
    bases-legais-retencao.md        # reference: a tabela que se consulta

2. Um documento de verdade. Cada arquivo abre com um cabeçalho que o sistema lê. O Purpose pesa o dobro do corpo no ranqueamento da busca, atrás só do título, então vale escrevê-lo com cuidado:

# Bases legais de retenção por tipo de dado

> **Purpose**: Quanto tempo cada categoria de dado pode ser retida e sob que base legal
> **Confidence**: 0.92
> **Fonte**: Lei 13.709/2018, arts. 7 e 16

## Overview

Retenção segue a finalidade e a base legal. Dados fiscais e contábeis
seguem prazos setoriais próprios. Dados de marketing caem com a
revogação do consentimento.

## Regra prática

| Categoria   | Prazo mínimo | Base legal                    |
|-------------|--------------|-------------------------------|
| Fiscal      | 5 anos       | obrigação legal (art. 7, II)  |
| Cadastral   | vigência     | execução de contrato          |
| Marketing   | nenhum       | consentimento (revogável)     |

3. A carta. É a parte que a maioria pula e é a que mais rende. A carta não é um guardrail que trava a execução: ela é o contexto que aparece para você na hora de aprovar, e o que obriga o refino a fechar as pontas antes de propor um contrato.

4. A prova de que funcionou. Quando o agente consulta a KB durante um trabalho, nasce um elo. Ele guarda a pergunta e a referência exata, nunca o corpo do documento:

{
  "event_type": "kb.consulted",
  "payload": {
    "query": "prazo de retencao dado fiscal expurgo",
    "refs": [{
      "kb_slug":      "lgpd_retencao",
      "doc_slug":     "bases-legais-retencao",
      "kind":         "reference",
      "content_hash": "9f2c...",     // reconstrói o que ele leu
      "snapshot":     3,             // a versão publicada
      "score":        0.61,
      "confidence":   0.92
    }]
  }
}

Guia: escrever uma boa Spec

A Spec é o contrato. Spec bem definida é loop confiável. Spec vaga é retrabalho garantido.

Uma Spec forte tem três partes, todas verificáveis:

• Escopo: o que está dentro e o que fica de fora. Ambiguidade aqui vira recusa no gate.
• Contratos de saída: o formato e as garantias do resultado (o que a entrega deve conter e como será conferida).
• Critérios de aceite: uma lista objetiva que o revisor usa para julgar. Se um humano não consegue dizer "passou" ou "não passou" olhando o critério, ele está fraco.

O mesmo pedido, escrito de dois jeitos

Deixe o refino consultar a KB e ancorar cada parte da Spec no domínio. Onde a KB impõe uma restrição que bloqueia, torne-a explícita no contrato: repare que o AC 1 do exemplo acima é a boundary da KB de LGPD virando critério verificável. Produzir a melhor Spec possível é a tarefa central do agente de refino.

Guia: configurar o Turno da Fábrica

Configure em Configurações, na aba Turno da Fábrica, por workspace:

# exemplo de política noturna
Janela        22:00 → 06:00   # fuso do workspace; pode cruzar a meia-noite
Orçamento     US$ 20 / dia     # estourou, pausa até amanhã
Auto-pausa    ≥ 30% de erro    # amostra mínima antes de agir
Re-enfileirar 1x               # teto de tentativas por task
Digest        webhook assinado # resumo matinal do que rodou
Concorrência  configurável     # quantas tasks em paralelo

Depois, monte o lote em /lote: escolha o projeto, marque as tasks prontas, o agente executor e um "não antes de" opcional. Cada task mantém seu próprio registro de atribuição; nada no lote aprova entrega.

Guia: políticas de gate

O gate é sempre humano, mas você define o rigor por workspace.

• Maker-checker. Exija N aprovadores distintos e separação de funções (quem executou não aprova). Uma violação vira registro.
• Preflight de atribuição. Antes do gatilho, o sistema antecipa problemas (Spec exigida, KB, conexão/chave, provedor/modelo, juiz, composição). Avisos não bloqueiam por padrão.
• Bloqueio por política. O workspace pode promover certos avisos a bloqueio duro. Por exemplo, tornar "rodar sem KB" um impeditivo de atribuição.

Boas práticas

Referência técnica

Estados da task e transições

Os estados de execução seguem uma máquina fechada por allow-list. As transições de planejamento (rascunho e pronta) têm autoridade própria e não passam por ela.

rascunho  → na fila           # atribuição (gatilho único)
pronta    → na fila           # atribuição pós-refino
na fila   → executando        # o worker reivindica
executando→ bloqueada por gate # abre o gate
bloqueada → concluída          # humano aprova
bloqueada → pronta / na fila   # recusa ou reatribuição
qualquer terminal → na fila    # re-disparo é re-atribuir

Tipos de elo na cadeia

Cada ação vira um elo tipado. Os principais:

• task.assigned, task.started: o gatilho e o início.
• kb.consulted: a consulta à KB, com o documento citado, hash e relevância.
• agent.model_invoked: uma invocação de modelo, com custo re-derivado pelo servidor.
• agent.tool_called: uma ferramenta chamada, com argumentos e resultado.
• agent.executed, agent.validated: a saída e o parecer do revisor.
• gate.opened, gate.decided: a abertura e a decisão humana.
• work_items.materialized: os filhos criados ao aprovar uma decomposição.

Stack

Backend em Python com FastAPI e PostgreSQL. Orquestração por fila no Postgres e worker assíncrono, sem Temporal ou Celery no v1. Agentes por harness próprio com tool-calling nativo do provedor, sem frameworks de orquestração como espinha. Segredos em cofre. A cadeia é protegida por gatilhos de banco, defesa em profundidade além da aplicação.

Os invariantes

As regras que o sistema garante. Cada uma tem um teste que falha se for violada.

Glossário

Perguntas frequentes