O problema de profundidade versus contexto em agentes de IA
Um desafio recorrente em fluxos de trabalho de pesquisa com Inteligência Artificial (IA) é o equilíbrio entre profundidade e contexto. Quando um agente lê dez páginas da web, a janela de contexto — a quantidade de texto que um Modelo de Linguagem Grande (LLM, do inglês Large Language Model) consegue processar de uma vez — fica saturada com conteúdo bruto. Se o agente também executa análise de dados, a lógica de geração de gráficos compete com o raciocínio estratégico pelo espaço disponível.
A saída tradicional para esse problema costuma ser encadeamento manual de prompts ou processamento sequencial. A AWS apresentou uma abordagem mais eficiente: delegar o trabalho aprofundado a subagentes isolados que retornam apenas resultados concisos. É exatamente esse o papel do LangChain Deep Agents, que cuida da orquestração, criando subagentes efêmeros especializados e gerenciando seu ciclo de vida.
Para prover a infraestrutura que cada subagente precisa, entra em cena o Amazon Bedrock AgentCore. Ele oferece um browser real dentro de uma MicroVM (Máquina Virtual Micro, do inglês MicroVM — uma máquina virtual leve e de propósito único) para pesquisa na web, além de um ambiente Python completo para análise de dados. O AgentCore também está disponível como provedor nativo de sandbox na CLI do Deep Agents, permitindo experimentar o CodeInterpreter do AgentCore com o simples comando deepagents --sandbox agentcore, sem precisar construir um agente completo.
O que você vai construir
O exemplo apresentado pela AWS é um agente de pesquisa competitiva que demonstra o padrão de ponta a ponta. O fluxo funciona assim:
- O agente coordenador recebe a solicitação e consulta o AgentCore Memory em busca de insights de pesquisas anteriores.
- Em seguida, ele dispara três subagentes de browser em paralelo, cada um navegando no site de um concorrente diferente dentro da sua própria MicroVM do AgentCore Browser.
- Quando os três retornam com os dados estruturados, um subagente analista recebe o conjunto combinado e usa o AgentCore Code Interpreter para gerar um gráfico comparativo e um relatório em markdown.
- Por fim, os principais insights são salvos no AgentCore Memory para uso em sessões futuras.
Todo o fluxo pode ser rastreado pelo Amazon CloudWatch via Amazon Bedrock AgentCore Observability ou pelo LangSmith. Cada tipo de subagente acessa apenas seu conjunto específico de ferramentas: ferramentas de browser para os pesquisadores, ferramentas de interpretação para o analista e ferramentas de memória para o coordenador.
Como construir o agente passo a passo
A construção envolve configurar um modelo, criar toolkits para cada tipo de subagente e conectar tudo com o LangChain Deep Agents.
Pré-requisitos
- Uma conta AWS com acesso ao Amazon Bedrock AgentCore habilitado
- Credenciais AWS configuradas como variáveis de ambiente (
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,AWS_REGION) ou via perfil do AWS CLI - Python 3.11 ou superior com pip ou uv para instalação de pacotes
- (Opcional) Amazon CloudWatch Transaction Search habilitado para visualizar traces e spans do AgentCore Observability
- (Opcional) Uma conta LangSmith para observabilidade
- (Opcional) Um recurso de AgentCore Memory com ao menos uma estratégia de extração configurada
- (Opcional) Um notebook Jupyter executável no repositório de amostras langchain-aws para a implementação completa
Passo 1: Configurar o modelo
O código abaixo configura o LLM que orquestra o agente. O exemplo acessa o Claude Sonnet pelo Amazon Bedrock:
from langchain_aws import ChatBedrockConverse
from langchain_aws.tools import create_browser_toolkit, create_code_interpreter_toolkit
from deepagents import create_deep_agent
from botocore.config import Config as BotoConfig
model = ChatBedrockConverse(
model="us.anthropic.claude-sonnet-4-6",
region_name="us-west-2",
config=BotoConfig(read_timeout=300),
)O prefixo us. utiliza um perfil de inferência entre regiões para maior disponibilidade. Também é possível usar o ID do modelo base diretamente.
Passo 2: Criar os toolkits de browser
Cada concorrente recebe seu próprio BrowserToolkit, que provisiona sua própria MicroVM do AgentCore Browser, garantindo isolamento completo entre os pesquisadores paralelos. O toolkit gerencia a concorrência quando o LLM emite múltiplas chamadas de ferramenta de browser em um único turno:
COMPETITORS = [
("GitHub", "https://github.com/pricing"),
("GitLab", "https://about.gitlab.com/pricing"),
("Bitbucket", "https://www.atlassian.com/software/bitbucket/pricing"),
]
toolkits_to_cleanup = []
research_subagents = []
for company_name, company_url in COMPETITORS:
browser_toolkit, browser_tools = create_browser_toolkit(region="us-west-2")
browser_toolkit.session_manager.session_wait_timeout = 60.0
toolkits_to_cleanup.append(browser_toolkit)
research_subagents.append({
"name": f"research-{company_name.lower()}",
"description": f"Researches {company_name} by browsing {company_url}.",
"system_prompt": RESEARCHER_PROMPT,
"tools": browser_tools,
})Cada MicroVM executa um browser Chromium real conectado via WebSocket usando Playwright (uma biblioteca de automação de browser de código aberto). As sessões são efêmeras e inicializam em segundos. O session_wait_timeout está definido em 60 segundos (padrão: 10 segundos) para dar tempo suficiente às operações de browser quando múltiplas chamadas de ferramenta rodam em paralelo. As ferramentas de browser incluem: navigate_browser, extract_text, click_element, type_text, scroll_page, extract_hyperlinks e wait_for_element.
Passo 3: Criar o toolkit do interpretador
O subagente analista usa o AgentCore Code Interpreter, uma MicroVM isolada com um ambiente Python completo com pandas, matplotlib e numpy pré-instalados:
ci_toolkit, ci_tools = await create_code_interpreter_toolkit(region="us-west-2")
toolkits_to_cleanup.append(ci_toolkit)
analyst_subagent = {
"name": "data-analyst",
"description": "Analyzes competitor data, generates charts and reports.",
"system_prompt": ANALYST_PROMPT,
"tools": ci_tools,
}As ferramentas do interpretador incluem: execute_code, execute_command, write_files, read_files, list_files, upload_file e install_packages. Bibliotecas adicionais podem ser adicionadas em tempo de execução com a ferramenta install_packages.
Passo 4: Adicionar memória entre sessões (opcional)
O agente coordenador pode acumular conhecimento ao longo do tempo com as ferramentas de memória do AgentCore, que interagem diretamente com a API de memória de longo prazo:
from bedrock_agentcore.memory import MemoryClient
from langchain_core.tools import tool
memory_client = MemoryClient(region_name="us-west-2")
@tool
def save_research_insights(insights: str, session_id: str = "default") -> str:
"""Save competitive research insights to AgentCore long-term memory."""
memory_client.create_event(
memory_id=memory_id,
actor_id=actor_id,
session_id=session_id,
messages=[
(f"Save these research insights:\n\n{insights}", "USER"),
("Insights saved to long-term memory.", "ASSISTANT"),
],
)
return "Insights saved and are extracted into long-term memory."Um ponto importante: o recurso de AgentCore Memory precisa ter ao menos uma estratégia de extração configurada (como semanticMemoryStrategy) para que o recall de longo prazo funcione. Sem estratégias, o create_event armazena eventos brutos, mas nenhum insight é extraído para recuperação futura. Quando o agente salva insights, as estratégias configuradas do AgentCore Memory extraem automaticamente o conhecimento estruturado em segundo plano.
Passo 5: Criar e executar o agente
Com todos os componentes prontos, basta conectá-los e invocar o agente:
agent = create_deep_agent(
model=model,
subagents=[*research_subagents, analyst_subagent],
tools=memory_tools,
system_prompt=COORDINATOR_PROMPT,
name="competitive-research-coordinator",
checkpointer=None, # Simplification; use AgentCoreMemorySaver for session resumability
store=InMemoryStore(), # Internal storage for Deep Agents (separate from AgentCore Memory)
)
result = await agent.ainvoke(
{"messages": [{"role": "user", "content": "Compare pricing for GitHub, GitLab, and Bitbucket"}]},
config={"configurable": {"thread_id": "session-1", "actor_id": "research-agent"}},
)O notebook executável com indicadores de progresso e exibição de sessão está disponível no notebook de acompanhamento. O tempo de execução esperado é de 4 a 6 minutos com o Claude Sonnet, refletindo o tempo real de navegação em três sites. O processamento sequencial da mesma pesquisa levaria até 3 vezes mais tempo.
Rastreamento e depuração do agente
O AgentCore Observability oferece visibilidade sobre essa arquitetura multi-agente pelo Amazon CloudWatch. O AgentCore emite traces e spans no formato OpenTelemetry (OTEL), permitindo visualizar a hierarquia completa de orquestração na página CloudWatch GenAI Observability: a execução do coordenador no nível superior, um span filho para cada subagente de pesquisa e o subagente analista na sequência.
Dentro de cada span, é possível revisar chamadas de ferramentas com seus inputs, outputs, tempo de execução e uso de tokens, confirmar que os subagentes de pesquisa rodaram em paralelo pelo tempo de relógio, e identificar qual subagente e chamada de ferramenta encontrou um problema quando uma navegação de browser ou execução de código não é bem-sucedida.
Como configuração única por conta, é necessário habilitar o CloudWatch Transaction Search antes que os traces e spans fiquem disponíveis. Ao hospedar o agente no AgentCore Runtime, o runtime instrumenta o agente com OTEL automaticamente, sem necessidade de configuração adicional. Para rodar o mesmo agente fora do runtime, basta adicionar o SDK do AWS Distro for OpenTelemetry (ADOT) e a biblioteca de instrumentação do LangChain ao agente. Mais detalhes na documentação do Amazon Bedrock AgentCore Observability.
Também é possível avaliar a qualidade dos traces com o Amazon Bedrock AgentCore Evaluations, que oferece avaliadores integrados como taxa de sucesso de objetivos e precisão na seleção de ferramentas. Consulte a documentação do AgentCore Evaluations para mais detalhes.
Para quem preferir, o LangSmith também pode ser usado para rastreamento. Com ele, basta configurar três variáveis de ambiente para ativar o rastreamento automático:
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY="your-langsmith-api-key"
export LANGCHAIN_PROJECT="competitive-research-agent"Por que essa arquitetura faz sentido
Existem quatro razões principais que tornam esse padrão valioso. Primeiro, o coordenador permanece focado no raciocínio de alto nível, pois cada subagente de pesquisa lida internamente com a navegação em múltiplas etapas e retorna apenas um resumo conciso. Segundo, há separação clara entre capacidades: cada tipo de subagente acessa apenas suas próprias ferramentas, reduzindo o risco de uso não intencional de ferramentas e tornando a depuração mais direcionada. Terceiro, a pesquisa roda mais rápido, já que três tarefas de browser executam em paralelo, cada uma em sua própria MicroVM do AgentCore. Por fim, o Amazon Bedrock AgentCore é agnóstico de modelo e de framework — as ferramentas do AgentCore (Browser, Interpreter, Memory) funcionam de forma idêntica independentemente do modelo que as orquestra. A troca de modelo é feita com uma única linha de código:
# Default: Amazon Bedrock
from langchain_aws import ChatBedrockConverse
model = ChatBedrockConverse(model="us.anthropic.claude-sonnet-4-6", region_name="us-west-2")
# Alternative: Anthropic API directly
# from langchain_anthropic import ChatAnthropic
# model = ChatAnthropic(model="claude-sonnet-4-6")
# Alternative: Google Gemini
# from langchain_google_genai import ChatGoogleGenerativeAI
# model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")Hospedando o agente no AgentCore Runtime
O agente construído funciona em um notebook, o que é ideal para desenvolvimento. Para movê-lo para um endpoint gerenciado com isolamento por sessão e um ARN de invocação estável, a AWS permite hospedá-lo no Amazon Bedrock AgentCore Runtime. O AgentCore Runtime hospeda o agente em um container ARM64 e executa cada sessão em uma microVM dedicada por até 8 horas. Por ser agnóstico de framework, o coordenador do Deep Agents, os subagentes de browser em paralelo e o subagente analista rodam sem nenhuma alteração.
A AgentCore CLI gerencia o fluxo de implantação em quatro etapas: criar o scaffold do projeto com agentcore create, atualizar o template com o código do agente, implantar com agentcore deploy e invocar com agentcore invoke. Após a implantação, é possível transmitir logs com agentcore logs e inspecionar traces com agentcore traces. Para encerrar, agentcore remove all seguido de agentcore deploy desfaz todos os recursos provisionados.
Limpeza dos recursos
Para evitar cobranças indesejadas, é importante limpar os recursos do AgentCore criados:
# Clean up browser sessions
for toolkit in browser_toolkits:
await toolkit.cleanup()
# Clean up interpreter session
await ci_toolkit.cleanup()As sessões de browser expiram automaticamente após 1 hora. As sessões do interpretador expiram após 15 minutos. O notebook de acompanhamento inclui código de limpeza que roda automaticamente. Se um recurso de AgentCore Memory tiver sido criado e não for mais necessário, ele pode ser excluído pelo console ou pela API do Amazon Bedrock AgentCore.
Próximos passos e casos de uso
O padrão de coleta paralela de dados, processamento especializado e síntese se aplica a muitos fluxos de trabalho além da pesquisa competitiva:
- Due diligence: configure subagentes para pesquisar registros financeiros, comunicados à imprensa e documentos regulatórios de uma empresa-alvo, trocando as URLs dos concorrentes por páginas de registros do SEC EDGAR e reutilizando o mesmo padrão de subagente de browser com mudanças mínimas.
- Criação de conteúdo: use subagentes de pesquisa para reunir material-fonte enquanto um subagente de escrita rascunha as seções.
- Orquestração de pipeline de dados: tenha subagentes extraindo dados de fontes diferentes e passando os resultados combinados para um subagente analista responsável por joins e transformações.
Para começar, abra o notebook de acompanhamento e siga o passo a passo célula por célula. Para mais informações sobre os serviços utilizados, consulte a documentação do LangChain Deep Agents, a documentação do Amazon Bedrock AgentCore, a página de preços do Amazon Bedrock AgentCore, a documentação do LangSmith, o repositório langchain-aws no GitHub e o guia de introdução ao Amazon Bedrock AgentCore.
Fonte
Build context-rich research agents with Deep Agents and Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/build-context-rich-research-agents-with-deep-agents-and-bedrock-agentcore/)
Leave a Reply