Como criar agentes de IA personalizados: arquitetura, padrões e escala

Passo 1: defina a arquitetura do agente de IA e a estrutura de controlo

A arquitetura de um agente de IA tem duas partes principais: o modelo e o serviço que o envolve. Esse serviço reúne o modelo, as suas ferramentas, a memória e os restantes componentes. Funciona como software determinístico, programado com lógica do tipo if/else em torno do modelo central.

A distinção é clara. Ao aprender a criar agentes de IA personalizados, muitas equipas cometem o erro de pedir ao modelo que faça tudo, o que causa graves problemas de fiabilidade.

Essa abordagem falha logo à partida. O modelo gera texto, mas a camada de controlo executa a lógica. Por isso, trate o modelo como um motor de raciocínio isolado, sem acesso direto ao código de encaminhamento.

A camada de controlo gere o estado, o encaminhamento e a recuperação de erros. O modelo nunca toma essas decisões. Depois de implementarmos esta arquitetura numa empresa SaaS de médio porte, os tempos de resolução dos pedidos de suporte caíram 40 por cento, porque a camada determinística encaminhava os pedidos corretamente, sem depender de suposições do modelo.

Foi o código que fez a diferença. Um fluxo de sistema claro ajuda a visualizar esta separação: é a camada de controlo, não o modelo, que determina o fluxo. Isso exige um plano de implementação rigoroso.

Não dispense as condições lógicas determinísticas. A Anthropic publicou um artigo que descreve possíveis padrões de arquitetura para agentes de IA, agrupados em quatro tipos básicos de sistema: agente único, fluxos de trabalho sequenciais, fluxos de trabalho paralelos e avaliador-otimizador.

Quer saber como criar agentes de IA personalizados capazes de crescer em escala? Escolha o padrão de acordo com o problema: obrigar um único agente a gerir um fluxo paralelo com várias etapas prejudica gravemente a latência do sistema. Agentes únicos executam bem uma tarefa de cada vez.

• [ ] Definir a lógica de encaminhamento determinística
• [ ] Planear o acesso às ferramentas por meio de MCP
• [ ] Selecionar o modelo de base
• [ ] Definir o esquema do estado da memória
• [ ] Configurar alternativas para recuperação de erros

Qual padrão de arquitetura se adapta ao seu agente personalizado?

São fáceis de depurar, mas têm um âmbito limitado. Nos fluxos de trabalho sequenciais, a saída de um agente passa para o seguinte, o que funciona bem em processos lineares, como pipelines de pesquisa que exigem a execução rigorosa de cada etapa. Nos fluxos de trabalho paralelos, um grupo de agentes de IA executa tarefas de forma assíncrona e simultânea, à semelhança da execução com múltiplas threads nos sistemas tradicionais, para reduzir a latência.

Este padrão reduz drasticamente a latência de tarefas complexas. Na arquitetura avaliador-otimizador, dois sistemas de agentes trabalham em ciclos iterativos: o Grupo A executa o trabalho e o Grupo B avalia-o e melhora-o, de forma semelhante à programação em pares.

O resultado tem mais qualidade em tarefas de programação ou escrita. O trecho de Python a seguir configura um fluxo de trabalho paralelo em que os agentes atuam de forma assíncrona. É assim que se executam vários agentes sem esperar que cada um termine para iniciar o seguinte.

Veja o código abaixo. `async def run_agent(task: str):`

# Simulate asynchronous agent task await asyncio.sleep(1)

import asyncio


return f"Result for {task}" async def parallel_workflow(tasks: list[str]): # Agents act asynchronously like multithreading results = await asyncio.gather(*[run_agent(task) for task in tasks])


return results tasks = ["fetch_market_data", "analyze_sentiment", "check_compliance"] results = asyncio.run(parallel_workflow(tasks)) print(results)

Ao conceber o fluxo de trabalho, considere estas vantagens e desvantagens. Para criar um agente de IA com Claude, os programadores combinam o Claude Agent SDK com Agent Skills. Se está a pesquisar como criar agentes de IA personalizados, tem assim dois caminhos principais.

Escolha as ferramentas com cuidado. Pode usar o Claude Agent SDK para uma integração estreita ou LangGraph para orquestrar máquinas de estados complexas.

1. Latência: os fluxos de trabalho paralelos reduzem drasticamente o tempo total.
2. Custo: os fluxos de trabalho paralelos consomem mais tokens por segundo.
3. Precisão: os ciclos avaliador-otimizador melhoram a precisão, mas duplicam o processamento.
4. Complexidade: os fluxos de trabalho sequenciais são os mais fáceis de depurar.

Passo 2: escolha o modelo de base e a estrutura de orquestração

A forma de pensar na criação de agentes com Claude é simples. O SDK gere o ciclo de execução, as ferramentas e o MCP definem o que o agente pode fazer, e as Skills definem o que ele sabe fazer. Assim, cada componente tem uma função clara.

O Claude Agent SDK fornece um ciclo de execução do agente (recolher contexto, chamar o modelo, executar uma ferramenta, devolver o resultado ao modelo e repetir) que pode ser programado em Python ou TypeScript. LangGraph oferece mais controlo. Permite definir nós explícitos de lógica num grafo e criar limites rigorosos que impedem o modelo de executar chamadas indevidas a ferramentas.

A camada de orquestração estabelece limites essenciais para manter os agentes focados na tarefa. Esses limites podem ser programados com ferramentas como LangGraph ou configurados em interfaces gráficas como Cursor Automations. Sem orquestração, um agente pode ficar preso num ciclo infinito devido a um único erro.

A gestão segura de credenciais é essencial. Nunca inclua chaves de API diretamente no prompt de sistema: em sistemas de produção, a única abordagem segura é fornecê-las durante a execução por meio de variáveis de ambiente.

Preferimos LangGraph para encaminhamento complexo. Obriga a pensar nas transições de estado, enquanto o Claude SDK é mais adequado à prototipagem rápida e a tarefas que usam muitas ferramentas e exigem iterações rápidas.

{
 "orchestration": {
 "guardrails": {
 "max_iterations": 5,
 "timeout_seconds": 30
 },
 "secrets_manager": {
 "provider": "aws_secrets_manager",
 "keys": ["ANTHROPIC_API_KEY", "FIRECRAWL_API_KEY"]
 }
 }
}

Passo 3: implemente ferramentas, acesso à web e gestão da memória

Os agentes de IA usam MCP (Model Context Protocol), ferramentas de linha de comandos e estruturas como LangChain para aceder a ferramentas. Saber criar agentes de IA personalizados também implica saber ligá-los à realidade. O conhecimento dos agentes de IA precisa de estar fundamentado em dados reais e em tempo real; sem isso, fica limitado às informações guardadas na memória e aos dados de treino.

As ferramentas integradas para obter páginas, disponibilizadas por empresas como OpenAI e Anthropic, oferecem acesso limitado à web. Por isso, são necessárias ferramentas específicas, como Firecrawl. Obter HTML bruto desperdiça espaço de contexto e confunde o modelo.

Firecrawl disponibiliza três endpoints principais para acesso à web: /search (pesquisas na web em tempo real), /scrape (obtenção de sites como dados estruturados ou Markdown) e /interact (abertura de um navegador real para clicar em botões e preencher formulários).

Numa página típica, a extração limpa com Firecrawl produz cerca de 2,788 tokens de Markdown, em vez de 38,381 tokens de HTML bruto. Firecrawl devolve 94 por cento menos tokens de entrada do que a obtenção de HTML bruto. Isto melhora diretamente o desempenho do agente.

A estrutura das páginas web pode mudar, e as páginas podem incluir menus ou scripts irrelevantes. Quando existir, prefira um endpoint estruturado e documentado. Teste também a extração com páginas representativas e diferentes disposições.

import requests


def search_web(query: str):
    response = requests.post("https://api.firecrawl.dev/v1/search", 
        json={"query": query, "limit": 5},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()


def scrape_site(url: str):
    response = requests.post("https://api.firecrawl.dev/v1/scrape",
        json={"url": url, "formats": ["markdown"]},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()

A memória é essencial para sistemas de IA de longa duração, porque todos os modelos funcionam com uma janela de contexto finita que é reiniciada quando atinge o limite. Essa janela pode ter, por exemplo, 200,000 tokens. Depois de atingido o limite, é necessário reconstruir o contexto com recurso à memória.

Guarde o histórico da conversa e o estado numa base de dados externa. Quando a janela de contexto ficar cheia, recupere um resumo e os factos relevantes. Depois, reconstrua o prompt. Nunca parta do princípio de que o modelo se lembra de algo que não esteja na entrada atual.

Como gerir custos, chaves de API e testes?

Se executar cinco agentes em simultâneo, paga cinco chamadas ao modelo ao mesmo tempo. Os agentes individuais custam menos por execução, mas demoram muito mais a concluir o trabalho. É preciso equilibrar rapidez e orçamento.

Vejamos um exemplo de um agente de suporte com um volume médio de pedidos: 10,000 execuções por mês, com um custo manual de $5 por ticket, num total de $50,000. Os custos da automação distribuem-se de outra forma.

O alojamento custa $100. O ponto de equilíbrio é atingido quase de imediato. Testar o código que envolve o agente é indispensável: antes de colocar qualquer coisa em produção, simule falhas das ferramentas e teste exaustivamente a lógica de timeout.

Usamos casos de teste determinísticos para o código que envolve o agente e conjuntos de avaliações probabilísticas para o modelo. Nunca colocamos um agente em produção sem testar como recupera de erros. Pare de sobrecarregar os prompts de sistema.

As Agent Skills são pastas com um arquivo SKILL.md que ensina o agente a realizar tarefas especializadas. São carregadas apenas quando necessárias, por divulgação progressiva, para manter a janela de contexto livre de informação desnecessária. Se quer dominar a criação de agentes de IA personalizados, precisa de separar as responsabilidades.

Uma perspetiva pouco comum: por que o conhecimento sobre procedimentos deve ficar nas Skills

O modelo mental para criar agentes com Claude é simples: o SDK gere o ciclo de execução, as ferramentas e o MCP definem o que o agente pode fazer, e as Skills ensinam-lhe como fazer. As ferramentas são verbos; as Skills são manuais. Se colocar todas as instruções no prompt de sistema, desperdiça contexto: o modelo lê instruções de que não precisa para a tarefa em curso.

A divulgação progressiva resolve isso. O agente só carrega o arquivo SKILL.md quando precisa de executar aquela tarefa específica. Assim, a janela de contexto mantém-se enxuta e há menos alucinações.

Os agentes também se tornam modulares: pode atualizar uma Skill sem alterar a lógica central de orquestração.