Ferramentas
e Memória.

De Funções Python a Ferramentas Reais com @tool e Orquestração Multi-Tool

Sem ferramentas, até o modelo mais avançado responde apenas com texto genérico sobre o que você deveria fazer. Como transformar qualquer função Python em uma ferramenta que o agente descobre, parametriza e encadeia sozinho?

O Contrato entre LLM, Agente e Ferramentas (Figuras 2.1 e 2.2)

No Capítulo 2, os autores sintetizam a divisão de papéis: o LLM é o cérebro (raciocínio e decisão), as Tools são as mãos e os sentidos (execução e leitura do ambiente) e o Agent é o coordenador. A Figura 2.2 classifica as ferramentas em cinco famílias: Information Retrieval (busca web, SQL, RAG), Action Execution (e-mail, arquivos, APIs), Computation (calculadoras, REPL), Integration (S3, DynamoDB, Lambda, Slack) e Specialized (imagem, áudio, vídeo).

Para que uma função Python deixe de ser invisível ao agente, você precisa adicionar exatamente três elementos: 1) o decorator @tool do pacote strands; 2) type hints nos parâmetros e retorno; e 3) uma docstring clara explicando o objetivo e os argumentos (Args: / Returns:).

from strands import Agent, tool

# Passo 1: Transforme uma função Python em Tool com @tool, type hints e docstring
@tool
def calculate_tip(bill_amount: float, tip_percentage: float, num_people: int = 1) -> dict:
    """Calculate tip and split the bill among people.

    Args:
        bill_amount: Total bill amount in dollars
        tip_percentage: Tip percentage (e.g., 15, 18, 20)
        num_people: Number of people splitting the bill (default: 1)
    """
    tip = bill_amount * (tip_percentage / 100)
    total = bill_amount + tip
    per_person = total / num_people
    return {
        "bill": bill_amount,
        "tip": round(tip, 2),
        "total": round(total, 2),
        "per_person": round(per_person, 2)
    }

# Passo 2: Entregue a tool ao agente com modelo explícito no Amazon Bedrock
agent = Agent(
    model="us.anthropic.claude-sonnet-4-20250514-v1:0",
    tools=[calculate_tip]
)

# Passo 3: Pergunte em linguagem natural — sem escrever parser nem if/else!
response = agent("The bill is $85. What's a 20% tip, and how much does each person pay if we're splitting it 4 ways?")
print(response.message["content"][0]["text"])

Orquestrando Múltiplas Tools Especializadas (Padrão Single-Purpose)

Evite a tentação de criar uma “mega-tool” que faz tudo. Como recomenda a dica da página 35, construa ferramentas focadas e de propósito único — por exemplo, get_sales_data(quarter) para consultar, analyze_sales(revenue, deals, quarter) para calcular ticket médio e send_email(to, subject, body) para enviar o resumo. Ao receber um pedido composto como “Pull last quarter's sales data and email a summary to the team”, o agente decide a ordem exata e passa os dados de uma tool para a outra.

Conexão com o livro · Capítulo 2 (págs. 29–39) · Why do agents need tools?, From function to tool, When one tool isn't enough e Building your first tool-enabled agent.

O Ecossistema strands-agents-tools e Integração Nativa com AWS (use_aws)

Você não escreve seu próprio parser JSON nem sua própria biblioteca HTTP do zero. Como aproveitar dezenas de ferramentas prontas da comunidade Strands e operar serviços da AWS diretamente por linguagem natural?

Os 4 Pilares e o Catálogo da Tabela 2.1 (Figura 2.6)

O ecossistema de ferramentas do Strands apoia-se em quatro pilares: 1) Pre-built community tools (pip install strands-agents-tools); 2) Custom Python tools (@tool); 3) MCP tools (servidores padronizados); e 4) AWS service integrations. Veja as principais categorias prontas da Tabela 2.1:

from strands import Agent
from strands_tools import http_request, calculator, file_write, use_aws

# 1. Combinando múltiplas tools da comunidade sem programar sequência fixa
analyst = Agent(
    tools=[http_request, calculator, file_write],
    system_prompt="You help with data analysis tasks."
)
analyst("""
Fetch stock data from https://query1.finance.yahoo.com/v8/finance/chart/AAPL?interval=1d&range=5d,
extract the latest closing prices, calculate the average price over the period,
and save the results to stock_summary.txt
""")

# 2. Operando S3, DynamoDB e Lambda em linguagem natural com uma única tool: use_aws
aws_agent = Agent(
    tools=[use_aws, calculator],
    system_prompt="You are an AWS assistant that helps manage cloud resources."
)
aws_agent("List all S3 buckets in my account")
aws_agent("Look up customer ID 12345 in the DynamoDB customers table and update their email to newemail@example.com")
aws_agent("Invoke the Lambda function 'order-processor' with order ID 67890")

Conexão com o livro · Capítulo 2 (págs. 39–45) · The Strands Agents tool ecosystem, Pre-built community tools (Tabela 2.1) e AWS integration.

Tools Customizadas em Escala: Classes Compartilhadas, Async/Await e Agent Builder

Decorar funções soltas funciona bem no protótipo. Mas o que acontece quando seu agente em produção começa a abrir 50 conexões de banco por minuto ou faz o usuário esperar 8 segundos por chamadas de API sequenciais?

Resolvendo os 2 Gargalos Reais de Tools Customizadas (págs. 48–52)

1. O Problema de Conexão com Banco de Dados (Classes com Estado Compartilhado): quando 5 funções @tool independentes abrem e fecham connect_to_database() dentro de cada chamada, uma única pergunta pode abrir 4 ou 5 conexões (50–100 ms de handshake cada), esgotando rapidamente o limite padrão do MySQL (151) ou PostgreSQL (100). A solução é encapsular as tools relacionadas dentro de uma classe Python (ex.: class InventoryTools), abrir a conexão ou pool uma vez no __init__ (self.db) e passar os métodos decorados ([inventory.check_stock, inventory.update_stock]) ao agente.
2. Checks Lentos em Série (Concorrência com async def + invoke_async): se o agente precisa consultar 3 armazéns independentes (2 segundos cada) e depois consolidar (2 segundos), chamadas síncronas somam 8 segundos. Marcando a tool com async def e usando httpx.AsyncClient(), o Strands dispara as três chamadas em paralelo (total de 4 segundos!). Regra prática: só use async em tools I/O-bound; cálculos puros abaixo de 100 ms não precisam da complexidade extra.

import asyncio, httpx
from strands import Agent, tool

# Padrão 1: Compartilhando conexão de banco/API em uma classe
class InventoryTools:
    def __init__(self, db_conn):
        self.db = db_conn  # Conexão aberta uma única vez

    @tool
    def check_stock(self, product_id: str) -> str:
        """Check product stock."""
        return self.db.query("SELECT quantity FROM inventory WHERE id = %s", (product_id,))

# Padrão 2: Tool assíncrona para chamadas independentes em paralelo
@tool
async def check_warehouse_inventory(product_id: str, warehouse: str) -> int:
    """Check inventory at a specific warehouse."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.warehouse-{warehouse}.com/inventory/{product_id}")
        return response.json()["quantity"]

async def main():
    agent = Agent(tools=[check_warehouse_inventory])
    response = await agent.invoke_async("Can we ship 100 units of PROD-123? Check all warehouses.")
    print(response.message["content"][0]["text"])

Prototipagem Rápida com Strands Agent Builder (e Comparação com LangChain)

Para experimentar ideias sem escrever boilerplate, o Strands Agent Builder (pipx install strands-agents-builder) permite criar e testar ferramentas descrevendo o que você quer em inglês no terminal: no modo interativo (strands) ou comando direto (strands "Build a tool that monitors API rate limits..."), usando opcionalmente --kb <KNOWLEDGE_BASE_ID> para persistir tools no Bedrock. Já em comparação ao LangChain (pág. 54), o Strands prioriza código mínimo e integração nativa com AWS, enquanto o LangChain oferece controle explícito mais verboso e um ecossistema amplo multi-cloud.

Conexão com o livro · Capítulo 2 (págs. 46–54) · Building custom tools, The database connection problem, Slow warehouse checks, Strands Agent Builder e Building agents on LangChain.

Memória de Agentes: Curto Prazo, Arquitetura CoALA e os 6 Desafios de Produção

Um agente com ferramentas mas sem memória comporta-se como um estranho a cada nova conversa: se o usuário pergunta sobre Nova York e depois pergunta “Qual a melhor época para visitá-la?”, o sistema se perde. Como estruturar memória que transforma transações isoladas em continuidade?

Agentes Stateless vs. Stateful e a Taxonomia CoALA (Figuras 3.1 a 3.3)

Baseado na arquitetura cognitiva CoALA (Cognitive Architectures for Language Agents), o Capítulo 3 mostra que memória não é um bloco único — ela se divide em memória de trabalho e três formas de memória de longo prazo:

Os 6 Desafios Críticos e o Fluxo Operacional de 6 Passos (Figuras 3.4 e 3.5)

Implementar memória em escala traz seis desafios reais (Figura 3.4): 1) Storage scalability (custo de milhões de embeddings); 2) Memory refresh (atualizar fatos antigos sem corromper o restante); 3) Integration complexity (conectar LLM, vetores e SQL/NoSQL em tempo real); 4) Privacy & security (criptografia e risco de vazamento multi-tenant entre usuários); 5) Retrieval accuracy (equilibrar precisão e recall evitando ruído); e 6) Observability (entender por que o agente lembrou ou esqueceu algo).

Conexão com o livro · Capítulo 3 (págs. 57–67) · What is agent memory, Types of agent memory (CoALA), Challenges (Figura 3.4) e Workflows (Figura 3.5).

Memória na AWS, Agente Personalizado com Mem0 e Simulador de Contexto

Como escolher os serviços AWS certos para cada camada de memória e garantir, na prática, que as preferências de um usuário jamais vazem para a sessão de outro usuário?

Mapeando Memória para Serviços AWS (Figura 3.6 e Tabela 3.2)

Agente Personalizado com Strands + Bedrock + Mem0 + Isolamento (Figuras 3.7 a 3.11)

Na Seção Building a personalized agent with memory (págs. 71–77), o livro combina strands_tools.mem0_memory, Amazon Bedrock (Claude) e busca web (DDGS) criando instâncias isoladas por usuário (Mona Mona vs. Bunny Kaushik) com um SYSTEM_PROMPT explícito proibindo acesso cruzado às memórias de terceiros.

from strands import Agent, tool
from strands_tools import mem0_memory, use_llm
from ddgs import DDGS

@tool
def websearch(keywords: str, region: str = "us-en", max_results: int | None = 5) -> str:
    """Search the web for live information."""
    results = DDGS().text(keywords, region=region, max_results=max_results)
    return str(results) if results else "No results found."

def create_user_agent(user_name: str) -> Agent:
    system_prompt = f"""You are a personal assistant for {user_name}.
You should not access any other person's information than {user_name}.
If you are asked a question for another person, politely refuse to answer.
When you remember something, make sure to associate it with {user_name}."""
    return Agent(tools=[mem0_memory, use_llm, websearch], system_prompt=system_prompt)

# Agente isolado para Mona: lembra restrições alimentares e busca restaurantes em NYC
agent_mona = create_user_agent("Mona Mona")
agent_mona("I am a veggie lover and require low-sodium, decaffeined options.")
print(agent_mona("Find good restaurant options for me in NYC"))

Conexão com o livro · Capítulo 3 (págs. 67–77) · Implementing memory systems with AWS services (Figura 3.6, Tabela 3.2) e Building a personalized agent with Mem0.

Context Engineering, Otimização de Memória e Combate ao Context Rot

Despejar 1.000 páginas de dados ou todo o histórico de chat na janela de contexto faz o agente perder foco, ignorar detalhes críticos e cometer erros — um fenômeno chamado Context Rot. Como fazer curadoria cirúrgica do contexto?

Os 3 Pilares do Context Engineering (Figura 3.12) e as 5 Estratégias (Tabela 3.3)

Trate a janela de contexto como um recurso finito e precioso. Para extrair o máximo de raciocínio do modelo, equilibre três pilares: System Prompts (específicos sem serem frágeis), Tools (enxutas em tokens e sem sobreposição) e Few-Shot Examples (poucos exemplos diversos em vez de listas exaustivas de exceções). Quando a tarefa excede uma única janela, aplique as estratégias da Tabela 3.3:

Conexão com o livro · Capítulo 3 (págs. 77–81) · Context management and memory optimization (Figura 3.12 e Tabela 3.3).

Amazon Bedrock AgentCore Memory: Actors, Sessions, Namespaces e Estratégias

Enquanto o Mem0 é ótimo para começar rápido, aplicações corporativas exigem isolamento estrito por usuário, TTL automático, consolidação sem duplicatas e checkpoints gerenciados. Como funciona por dentro o Amazon Bedrock AgentCore Memory?

Arquitetura Interna: Curto Prazo (Raw Events) → Extração → Longo Prazo (Figuras 3.14 a 3.17)

Dentro da plataforma modular AWS AgentCore (Figura 3.13), o serviço AgentCore Memory separa o armazenamento bruto de curto prazo da memória semântica durável de longo prazo:

• Short-Term Memory (Figura 3.15): organizada em torno de Actor (quem interage — usuário ou par usuário-agente, garantindo isolamento), Events (mensagens e blobs JSON) e Session (uma conversa específica), sincronizando histórico de chat, estado da sessão e checkpoints restauráveis.
• Namespaces Hierárquicos (pág. 87): permitem dar “zoom in” ou “zoom out” na memória: / (Global: regras de compliance), /strategy/{strategyId} (Strategy: conhecimento de domínio compartilhado), /actor/{actorId} (Actor: preferências do usuário) e /session/{sessionId} (Session: resumos de uma conversa específica).
• Memory Strategies & Extraction Module (Figura 3.16): suporta estratégias Built-in, Built-in overrides e Self-managed. De forma assíncrona — a cada K = 12 mensagens ou 20 segundos de inatividade — o módulo executa Extraction (puxa sinais relevantes), Consolidation (operações ADD / UPDATE / SKIP consultando memórias similares para evitar duplicidade) e Embedding & Indexing no Vector Store para busca futura via Retrieve_memories (Figura 3.17).

from bedrock_agentcore.memory import MemoryClient

region = "us-east-1"
memory_name = "MathLanggraphAgent"

# Inicializa o cliente e cria o recurso gerenciado no AgentCore Memory
client = MemoryClient(region_name=region)
memory = client.create_memory(name=memory_name)
print("Memory ID criado:", memory["id"])

Conexão com o livro · Capítulo 3 (págs. 81–90) · Introducing Amazon Bedrock AgentCore Memory (Figuras 3.13 a 3.17).

Laboratório Prático: Agente Matemático com LangGraph e AgentCoreMemorySaver

Como unir a orquestração baseada em grafos do LangGraph (nós, arestas condicionais e laços) à persistência gerenciada do Amazon Bedrock AgentCore Memory para que o agente retome raciocínios multi-etapa sem perder o fio da meada?

Arquitetura do Math Agent com Checkpointing (Figuras 3.18 a 3.23)

No laboratório prático das páginas 90–97 (math-agent-with-checkpointing.ipynb), o AgentCoreMemorySaver atua como checkpointer backend do grafo criado por create_react_agent() (Figura 3.20: __start__ → agent ↔ tools → __end__). Em tempo de execução, o RuntimeConfig do LangGraph mapeia automaticamente thread_id para o session_id do AgentCore e actor_id para o actor_id do AgentCore, salvando cada passo intermediário e chamada de ferramenta.

from langchain.chat_models import init_chat_model
from langchain.tools import tool
from langgraph.prebuilt import create_react_agent
from langgraph_checkpoint_aws import AgentCoreMemorySaver

region = "us-east-1"
memory_id = "MyMemory-rYlaiv7u2Q"  # ID retornado por client.create_memory(...)
MODEL_ID = "global.anthropic.claude-haiku-4-5-20251001-v1:0"

# 1. Checkpointer persistente no Amazon Bedrock AgentCore Memory
checkpointer = AgentCoreMemorySaver(memory_id, region_name=region)

# 2. Modelo via interface Bedrock Converse
llm = init_chat_model(MODEL_ID, model_provider="bedrock_converse", region_name=region)

# 3. Ferramentas matemáticas
@tool
def add(a: int, b: int) -> int:
    """Add two integers and return the result."""
    return a + b

@tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers and return the result."""
    return a * b

graph = create_react_agent(
    model=llm,
    tools=[add, multiply],
    prompt="You are a helpful assistant",
    checkpointer=checkpointer,
)

# 4. RuntimeConfig mapeando thread_id -> session_id e actor_id -> actor_id
config = {
    "configurable": {
        "thread_id": "session-1",
        "actor_id": "react-agent-1"
    }
}

# Turno 1: cálculo multi-etapa (1337 * 515321 + 412 = 688,984,589)
inputs1 = {"messages": [{"role": "user", "content": "What is 1337 times 515321? Then add 412 and return the value to me."}]}
for chunk in graph.stream(inputs1, stream_mode="updates", config=config):
    print(chunk)

# Turno 2: testando persistência de memória na mesma sessão
inputs2 = {"messages": [{"role": "user", "content": "What were the first calculations I asked you to do?"}]}
for chunk in graph.stream(inputs2, stream_mode="updates", config=config):
    print(chunk)

Conexão com o livro · Capítulo 3 (págs. 90–97) · Hands-on lab: Using AgentCore Memory with LangGraph (Figuras 3.18 a 3.23).