Agent-Native

In partnership with

Introducing the first AI-native CRM

Connect your email, and you’ll instantly get a CRM with enriched customer insights and a platform that grows with your business.

With AI at the core, Attio lets you:

• Prospect and route leads with research agents

• Get real-time insights during customer calls

• Build powerful automations for your complex workflows

Join industry leaders like Granola, Taskrabbit, Flatfile and more.

👉Try Attio Pro for free

Acima temos o anunciante da News dessa semana 🚀 Se puder, clique no link do anunciante acima para deixar seu apoio (é grátis!) ❤️

Você abre um app "com IA". Digita: "Organize meus arquivos por data".

O agente responde: "Desculpe, não posso fazer isso. Mas posso te explicar como fazer."

Curioso, você vai na interface. Arrasta. Solta. Pronto, arquivos organizados.

Espera. O que?

O usuário consegue fazer com um gesto. Mas o agente — que deveria ser o assistente inteligente — não tem acesso à mesma capacidade. Ele pode falar sobre organizar arquivos, mas não pode fazer.

Esse é o pecado original de 90% dos apps "com IA" hoje: o agente não é um cidadão de primeira classe. Ele é um visitante na própria casa.

Mas existe uma arquitetura diferente. Apps onde agentes têm as mesmas capacidades que usuários. Onde você pede algo em linguagem natural e o agente faz, não apenas orienta.

Isso tem um nome: Agent-Native Architecture.

Se você está construindo produtos com IA — ou planeja construir — essa é a diferença entre um chatbot glorificado e um verdadeiro co-piloto.

🎯 O Princípio da Paridade: Agente = Usuário

A primeira regra da arquitetura agent-native é brutalmente simples:

Se o usuário pode fazer pela UI, o agente deve conseguir fazer via tools.

Pense nisso como acessibilidade, mas para agentes. Assim como você não criaria um app onde usuários de teclado não conseguem acessar funcionalidades disponíveis para usuários de mouse, você não deveria criar um app onde agentes não conseguem acessar o que usuários conseguem.

O teste é direto:

Pegue qualquer ação que um usuário pode fazer no seu app. Liste todas. Depois responda: "O agente consegue realizar essa ação através de ferramentas?"

Se a resposta for não, você tem uma lacuna de paridade.

O Mapa de Capacidades

Crie uma tabela simples:

Se qualquer linha tem a coluna do agente vazia, você tem trabalho a fazer.

A paridade não é um luxo. É o fundamento. Sem paridade, você não tem arquitetura agent-native. Você tem um chatbot com acesso limitado.

Mas paridade é só o começo. O próximo passo é mais sutil — e mais poderoso.

🔬 O Princípio da Granularidade: Ferramentas Atômicas, Comportamentos Emergentes

Aqui está onde a maioria erra.

Quando desenvolvedores começam a construir ferramentas para agentes, o instinto é criar ferramentas "inteligentes" que fazem muito:

# Errado
classify_and_organize_files(files) {
  // classifica por tipo
  // decide estrutura de pastas
  // move arquivos
  // cria relatório
}

Parece eficiente. Na verdade, é uma armadilha.

O problema: Você codificou a lógica em código. Se o usuário quiser classificar de forma diferente, você precisa refatorar. Se quiser organizar sem mover, você precisa criar outra tool. Se quiser apenas o relatório, mais uma tool.

Cada variação exige engenharia.

A alternativa agent-native:

# Certo
Tools disponíveis:
- read_file(path)
- write_file(path, content)
- move_file(from, to)
- list_directory(path)
- bash(command)

Prompt: "Organize meus downloads por conteúdo e data recente"

O agente compõe as ferramentas atômicas para realizar a tarefa. Quer mudar o comportamento? Mude o prompt, não o código.

O Teste da Prosa

Aqui está o teste definitivo: Para mudar o comportamento do sistema, você edita prosa ou refatora código?

Se a resposta é "refatora código", suas ferramentas não são granulares o suficiente.

Ferramentas atômicas criam uma propriedade mágica: composabilidade.

🧩 O Princípio da Composabilidade: Novos Recursos = Novos Prompts

Quando você tem paridade (agente pode fazer o que usuário faz) e granularidade (tools são atômicas), algo extraordinário acontece:

Novos recursos emergem sem escrever código.

Imagine o pedido: "Quero que o agente revise arquivos modificados esta semana, resuma mudanças e sugira três prioridades."

Num sistema bem construído, isso não exige código novo.

O agente já tem:

• list_files (com filtro de data)

• read_file (para ver conteúdo)

• Julgamento (para interpretar e sintetizar)

Basta um novo prompt:

"Revise arquivos modificados nos últimos 7 dias.
Para cada arquivo, resuma a mudança principal.
Depois, sugira três prioridades baseado no
momentum e impacto potencial."

O agente executa. Feature entregue em minutos, não sprints.

Isso é composabilidade. É o que acontece quando você constrói primitivas corretas ao invés de workflows pré-programados.

A Consequência Não-Óbvia

Quando você atinge composabilidade verdadeira, o roadmap de produto muda.

Ao invés de planejar "Feature X precisa de 2 sprints de eng + 1 sprint de design", você pergunta: "Isso é uma função nova “primitiva" ou uma nova composição das primitivas existentes?”

Se for composição, você muda o prompt. Se for primitiva, você adiciona uma tool.

A engenharia se concentra em expandir o vocabulário de ações básicas. O produto se concentra em orquestrar essas ações de formas úteis.

E isso libera a propriedade mais valiosa de todas.

🌟 O Princípio da Emergência: Faça o Impossível Possível

A verdadeira magia da arquitetura agent-native não é o que você planejou. É o que você nunca imaginou.

Capacidades emergentes.

Considere um app de notas com arquitetura agent-native. Um usuário pede: "Prepara uma apresentação usando minhas notas da última semana?"

Ninguém construiu um "modo apresentação". Mas o agente tem:

• search_notes (buscar por data)

• read_note (ler conteúdo)

• create_document (criar novo arquivo)

• Compreensão de linguagem (sintetizar e estruturar)

O usuário pede. O agente entrega.

Slides estruturados em Markdown. Temas categorizados. Insights conectando notas separadas que falavam sobre conceitos similares.

Ninguém programou isso. O agente descobriu como fazer usando as primitivas disponíveis.

Essa é a diferença entre um sistema agent-native e um sistema tradicional:

Em sistemas tradicionais, você mapeia casos de uso → features.

Em sistemas agent-native, você mapeia primitivas → vocabulário, e os casos de uso emergem.

O Ciclo de Evolução

1. Construa primitivas atômicas → ferramentas básicas com paridade

2. Usuários pedem coisas inesperadas → agente compõe soluções

3. Você observa padrões → quais composições são frequentes?

4. Otimize padrões comuns → transforme composições frequentes em atalhos

5. Repita

Você não está construindo um app. Você está cultivando um ecossistema de capacidades.

🛠️ Design de Tools: As Regras Práticas

Teoria é bonita. Mas como você realmente desenha tools agent-native?

Regra 1: Uma Ação Conceitual por Tool

# Errado - julgamento embutido
analyze_and_publish(input) {
  análise = analyze(input)
  if análise.score > 0.8:
    publish(análise.output)
}

# Certo - julgamento no prompt
Tools: analyze(input), publish(content)
Prompt: "Analise o input. Se a qualidade for alta, publique."

O primeiro embute lógica de negócio no código. O segundo deixa o agente decidir.

Regra 2: Mantenha Primitivas Disponíveis

Quando você adiciona ferramentas de domínio (como create_note), não esconda as primitivas (write_file).

Ferramentas de domínio são atalhos, não portões.

O agente deve sempre poder "descer um nível" se precisar de mais controle.

Regra 3: CRUD Completo Para Cada Entidade

Para toda entidade no seu sistema, o agente precisa:

• Create - criar novas instâncias

• Read - ver o que existe

• Update - modificar existente

• Delete - remover

Se qualquer uma dessas operações está faltando, o agente fica manco.

Regra 4: Descoberta Dinâmica de Capacidades

Ao invés de mapear estaticamente cada endpoint da API para uma tool:

# Duas tools manejam qualquer API
list_available_types() → ["steps", "heart_rate", "sleep", ...]
read_data(type) → lê qualquer tipo descoberto

O agente descobre capacidades em runtime. Quando a API adiciona novos endpoints, eles funcionam automaticamente.

Você construiu extensibilidade via descoberta, não via código.

📁 Files: A Interface Universal

Existe uma decisão arquitetural que separa os melhores sistemas agent-native dos medianos:

Use arquivos como interface primária.

Por quê?

1. Agentes já conhecem - Todo LLM moderno foi treinado com cat, grep, mv, mkdir

2. Usuários podem inspecionar - Files são transparentes, portáveis, sincronizam entre dispositivos

3. Estrutura de diretórios = arquitetura de informação - A organização dos arquivos comunica significado

O Padrão context.md

Um arquivo que o agente lê no início de cada sessão. A estrutura típica:

# Context

## Identidade
[Quem é o agente neste app]

## Conhecimento do Usuário
[Preferências, histórico, contexto relevante]

## Estado Atual
[O que existe no sistema, atividade recente]

## Diretrizes
[Regras específicas de comportamento]

Por que funciona? Contexto persistente, editável pelo usuário, versionável no git.

Para mudar o comportamento do agente, você edita um arquivo Markdown. Não refatora código.

Files vs. Database: O Guia de Decisão

O princípio: se o usuário precisa entender ou editar, use files. Se o sistema precisa consultar ou relacionar, use database.

🎭 Sinais de Completion: O Problema Invisível

Aqui está um problema que poucos desenvolvedores percebem até ser tarde demais:

Como o agente sabe quando parar?

A maioria usa heurísticas: "se não chamou nenhuma tool nas últimas 2 respostas, assumir que terminou."

Isso é uma bomba-relógio.

Heurísticas falham. O agente pode estar refletindo, não terminando. Ou pode ter travado, não estar refletindo.

A solução agent-native: completion explícito.

Cada resultado de tool carrega três informações:

• success: a operação funcionou?

• output: qual foi o resultado?

• shouldContinue: o agente deve continuar o loop?

Os padrões de uso:

• .success("Resultado") → operação ok, continuar trabalhando

• .error("Mensagem") → falhou mas é recuperável, continuar

• .complete("Concluído") → missão cumprida, parar o loop

O agente não "espera" o sistema detectar que terminou. Ele declara que terminou.

Completion Parcial

Projetos complexos têm múltiplas tarefas. Como rastrear progresso parcial?

Cada tarefa tem um status: pending, in_progress, completed, failed, ou skipped.

Checkpoint salva quais tarefas foram completadas. Se interromper, você retoma de onde parou.

Não começe do zero. Continue do checkpoint.

🚨 Anti-Patterns: O Que Evitar

Se você reconhecer qualquer um destes no seu sistema, você tem trabalho a fazer:

1. Agente Como Roteador

# Errado
user: "Organize meus arquivos"
agent: "Para organizar, use o menu Files > Organize"

O agente apenas orienta, não age. Ele é um manual, não um assistente.

Fix: Dê ao agente tools para organizar diretamente.

2. Ferramentas em Forma de Workflow

# Errado
analyze_categorize_move_report(files)

Toda a lógica está no código. Mudanças exigem engenharia.

Fix: Quebre em primitivas: analyze(), categorize(), move(), report().

3. Ações Órfãs na UI

Usuário pode fazer algo na interface que agente não pode fazer via tools.

Fix: Para cada ação na UI, crie tool correspondente.

4. Fome de Contexto

Agente não tem acesso a informações sobre estado do sistema, histórico recente, ou preferências do usuário.

Fix: Injete contexto no system prompt (via context.md ou similar).

5. Portões Sem Razão

Você esconde primitivas, forçando agente a usar apenas ferramentas de alto nível.

Fix: Sempre mantenha primitivas acessíveis. Ferramentas de domínio são atalhos, não restrições.

6. Detecção de Completion via Heurística

Sistema "adivinha" quando agente terminou.

Fix: Tool explícita de completion ou flag shouldContinue nos resultados.

✅ O Checklist de Arquitetura Agent-Native

Use isso para auditar seu app:

Arquitetura:

• [ ] Agente pode fazer qualquer coisa que usuário pode (paridade)

• [ ] Tools são primitivas atômicas (granularidade)

• [ ] Novos recursos = novos prompts (composabilidade)

• [ ] Agente resolve pedidos inesperados (capacidade emergente)

Implementação:

• [ ] System prompt inclui recursos e capacidades disponíveis

• [ ] Agente e usuário compartilham mesmo espaço de dados

• [ ] Ações do agente refletem imediatamente na UI

• [ ] Toda entidade tem CRUD completo

• [ ] Agente sinaliza completion explicitamente

Teste Final:

Descreva um resultado no seu domínio que você não construiu uma feature para.

O agente consegue descobrir como fazer usando as tools disponíveis?

Se sim, você tem arquitetura agent-native.

Se não, volte aos princípios: paridade, granularidade, composabilidade, emergência.

🔮 O Futuro Já Está Aqui

A diferença entre apps que têm IA e apps que são agent-native vai se tornar óbvia nos próximos meses.

Os primeiros vão parecer chatbots amarrados com arame. "Converse comigo, mas não espere que eu faça muito."

Os segundos vão parecer mágica. "Peça qualquer coisa. Se faz sentido, eu descubro como fazer."

A escolha não é se construir com IA. É como construir.

Você pode adicionar um chat e chamar de "app com IA". Ou pode repensar sua arquitetura do zero, tratando agentes como cidadãos de primeira classe com as mesmas capacidades que usuários.

Um é um feature. O outro é um paradigma.

E paradigmas comem features no café da manhã.

📚 Conteúdos Recomendados

📄 Artigo: Building Effective Agents — Anthropic - O guia oficial da Anthropic sobre como construir agentes eficazes.

📄 Artigo: Tool Use with Claude — Anthropic Docs - Documentação técnica sobre design de ferramentas para agentes.

🛠️ Ferramenta: Compound Engineering Plugin — Conjunto de agentes e skills para Claude Code que aplicam os conceitos do artigo e melhoram/aprendem a cada iteração.

Forte abraço,

Equipe Olympus