Este guia explica como executar e entender cada exemplo do framework.
- MCP Demo - Integração com Model Context Protocol
- Built-in Tools - Ferramentas integradas
- Multi-Provider - Múltiplos provedores LLM
- Objectives Demo - Sistema de objetivos
- Custom Tools - Criação de ferramentas customizadas
- Memory Demo - Sistema de memória (atualizado v0.10.0)
Arquivo: react_agent_framework/examples/mcp_demo.py
- Conexão com servidores MCP (Model Context Protocol)
- Uso de ferramentas de servidores externos
- Gerenciamento de múltiplos servidores
- Configuração pré-definida de servidores populares
# Instalar dependências MCP
pip install mcp
# Instalar servidor filesystem (Node.js)
npm install -g @modelcontextprotocol/server-filesystempython react_agent_framework/examples/mcp_demo.pyagent = ReactAgent(name="File Assistant", provider="gpt-4o-mini")
# Conectar ao servidor filesystem
server_id = agent.add_mcp_server(
command="npx",
args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
name="filesystem",
auto_register=True,
)
# Usar ferramentas do servidor
answer = agent.run("List the files in /tmp directory", verbose=True)# Conectar filesystem
fs_server_id = agent.add_mcp_server(...)
# Poderia conectar GitHub
# github_server_id = agent.add_mcp_server(
# command="npx",
# args=["-y", "@modelcontextprotocol/server-github"],
# env={"GITHUB_TOKEN": "ghp_..."},
# name="github",
# )
# Listar todos servidores conectados
for server in agent.list_mcp_servers():
print(f" - {server['name']} (ID: {server['id']}, Tools: {server['num_tools']})")from react_agent_framework.mcp.config import MCPConfigManager
# Listar servidores populares
for name, desc in MCPConfigManager.list_popular_servers().items():
print(f" - {name}: {desc}")
# Usar configuração pré-definida
config_manager = MCPConfigManager()
fs_config = config_manager.get_popular_server("filesystem")
server_id = agent.add_mcp_server(
command=fs_config.command,
args=fs_config.args,
env=fs_config.env,
name=fs_config.name,
)- MCP Server: Servidor externo que fornece ferramentas
- Auto-register: Registra automaticamente todas as ferramentas do servidor
- Server ID: Identificador único para gerenciar conexões
Arquivo: react_agent_framework/examples/builtin_tools.py
- Ferramentas integradas do framework
- Registro de ferramentas com pattern matching
- Combinação de múltiplas ferramentas
python react_agent_framework/examples/builtin_tools.pyagent = ReactAgent(name="Math Assistant", provider="gpt-4o-mini")
# Registrar ferramenta de cálculo
agent.use_tools("computation.calculator")
result = agent.run("What is 25 * 4 + 100 / 2?", verbose=True)agent = ReactAgent(name="File Assistant", provider="gpt-4o-mini")
# Registrar todas ferramentas de filesystem
agent.use_tools("filesystem.*")
result = agent.run("List all Python files in the current directory", verbose=True)agent = ReactAgent(name="Search Assistant", provider="gpt-4o-mini")
# Registrar ferramenta de busca
agent.use_tools("search.duckduckgo")
result = agent.run("What is the latest version of Python?", verbose=True)agent = ReactAgent(name="Multi-tool Assistant", provider="gpt-4o-mini")
# Registrar várias ferramentas específicas
agent.use_tools(
"search.duckduckgo",
"computation.calculator",
"filesystem.list",
)
result = agent.run(
"Search for the current Python version, calculate 2024 - 1991, and list current directory",
verbose=True,
)agent = ReactAgent(name="Super Assistant", provider="gpt-4o-mini")
# Registrar TODAS as ferramentas disponíveis
agent.use_tools("*")
print(f"Registered tools: {', '.join(agent.get_tools().keys())}")Computation:
computation.calculator- Calculadora matemática
Filesystem:
filesystem.read- Ler arquivofilesystem.write- Escrever arquivofilesystem.list- Listar diretóriofilesystem.delete- Deletar arquivo
Search:
search.duckduckgo- Busca web com DuckDuckGo
# Específico
agent.use_tools("computation.calculator")
# Categoria completa
agent.use_tools("filesystem.*")
# Múltiplas ferramentas
agent.use_tools("search.*", "computation.*")
# Todas
agent.use_tools("*")Arquivo: react_agent_framework/examples/multi_provider.py
- Suporte a múltiplos provedores LLM
- Diferentes formas de configuração
- Auto-detecção de provider
# Configure as API keys necessárias
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."
python react_agent_framework/examples/multi_provider.pyagent = ReactAgent(
name="OpenAI Assistant",
provider="gpt-4o-mini" # String simples, usa OpenAI por padrão
)agent = ReactAgent(
name="OpenAI URL Assistant",
provider="openai://gpt-4o-mini" # URL-style explícito
)agent = ReactAgent(
name="Claude Assistant",
provider="anthropic://claude-3-5-sonnet-20241022"
)from react_agent_framework.providers import AnthropicProvider
claude_provider = AnthropicProvider(
model="claude-3-5-sonnet-20241022",
# api_key="your-key-here" # Opcional, usa env
)
agent = ReactAgent(
name="Claude Object Assistant",
provider=claude_provider
)agent = ReactAgent(
name="Gemini Assistant",
provider="google://gemini-1.5-flash"
)# Requer Ollama rodando localmente
agent = ReactAgent(
name="Ollama Assistant",
provider="ollama://llama3.2"
)# Auto-detectado pelo prefixo do modelo
agent_claude = ReactAgent(provider="claude-3-5-sonnet-20241022") # → Anthropic
agent_gemini = ReactAgent(provider="gemini-1.5-flash") # → Google
agent_llama = ReactAgent(provider="llama3.2") # → Ollama| Provider | URL Format | Auto-detect Prefix | Requer API Key |
|---|---|---|---|
| OpenAI | openai://model |
gpt-* |
Sim |
| Anthropic | anthropic://model |
claude-* |
Sim |
google://model |
gemini-* |
Sim | |
| Ollama | ollama://model |
llama* |
Não (local) |
Arquivo: react_agent_framework/examples/objectives_demo.py
- Sistema de objetivos para agentes orientados a metas
- Tracking de progresso
- Prioridades e deadlines
- Sub-objetivos e hierarquias
- Persistência de objetivos
python react_agent_framework/examples/objectives_demo.pyfrom react_agent_framework.core.objectives import Objective, ObjectiveTracker
# Criar objetivos
obj1 = Objective(
goal="Research Python frameworks",
success_criteria=["Find 3+ frameworks", "Compare features"],
priority="high",
)
obj2 = Objective(
goal="Write documentation",
success_criteria=["Create README", "Add examples"],
priority="medium",
deadline=datetime.now() + timedelta(days=7),
)
# Criar tracker
tracker = ObjectiveTracker()
tracker.add(obj1)
tracker.add(obj2)
# Trabalhar no próximo objetivo
next_obj = tracker.start_next()
# Atualizar progresso
tracker.update_progress(next_obj.id, 0.5, "Found 2 frameworks so far")
# Completar
tracker.complete(next_obj.id, "Research completed successfully")objectives = [
Objective(
goal="Calculate the total cost of purchasing 15 items at $8.99 each",
success_criteria=["Perform calculation", "Provide final total"],
priority="high",
),
]
agent = ReactAgent(
name="Goal-Oriented Assistant",
provider="gpt-4o-mini",
objectives=objectives,
)
# Agent executa e pode marcar objetivos como completos
answer = agent.run("Calculate 15 * 8.99", verbose=False)
first_obj = agent.objectives.get_active()[0]
agent.objectives.complete(first_obj.id, "Calculation completed")tracker = ObjectiveTracker()
# Adicionar com diferentes prioridades
tracker.create(
goal="Fix critical security bug",
priority="critical",
deadline=datetime.now() + timedelta(hours=2),
)
tracker.create(
goal="Update documentation",
priority="low",
deadline=datetime.now() + timedelta(days=30),
)
# Objetivos são processados por prioridade
while tracker.get_pending():
obj = tracker.start_next() # Pega o próximo por prioridade
print(f"Working on: {obj.goal} (priority: {obj.priority.value})")
tracker.complete(obj.id, f"Completed {obj.goal}")# Objetivo principal
main_obj = Objective(
goal="Build and deploy web application",
priority="high",
)
# Adicionar sub-objetivos
main_obj.add_sub_objective(
Objective(goal="Design database schema", priority="high")
)
main_obj.add_sub_objective(
Objective(goal="Implement API endpoints", priority="high")
)
main_obj.add_sub_objective(
Objective(goal="Create frontend UI", priority="medium")
)
# Calcular progresso geral
overall_progress = sum(s.progress for s in main_obj.sub_objectives) / len(main_obj.sub_objectives)# Salvar objetivos
tracker_data = tracker.to_dict()
# Carregar objetivos
new_tracker = ObjectiveTracker.from_dict(tracker_data)- critical - Urgente, deve ser feito imediatamente
- high - Alta prioridade
- medium - Prioridade média
- low - Baixa prioridade
- Objective: Meta com critérios de sucesso
- ObjectiveTracker: Gerencia múltiplos objetivos
- Success Criteria: Lista de requisitos para completar
- Sub-objectives: Objetivos hierárquicos
- Progress: Porcentagem de conclusão (0.0 - 1.0)
Arquivo: react_agent_framework/examples/custom_tools.py
- Criação de ferramentas customizadas com decoradores
- Diferentes tipos de ferramentas
- Registro com nome e descrição personalizados
python react_agent_framework/examples/custom_tools.pyagent = ReactAgent(
name="Personal Assistant",
provider="gpt-4o-mini",
)
@agent.tool()
def get_datetime() -> str:
"""Get current date and time"""
now = datetime.now()
return f"Date: {now.strftime('%Y-%m-%d')}, Time: {now.strftime('%H:%M:%S')}"@agent.tool()
def random_number(range_str: str) -> str:
"""Generate random number. Input format: 'min-max' (e.g., '1-100')"""
min_val, max_val = map(int, range_str.split("-"))
number = random.randint(min_val, max_val)
return f"Random number between {min_val} and {max_val}: {number}"@agent.tool()
def convert_temperature(input_str: str) -> str:
"""Convert temperature. Format: 'C to F: 25' or 'F to C: 77'"""
if "C to F" in input_str:
celsius = float(input_str.split(":")[-1].strip())
fahrenheit = (celsius * 9 / 5) + 32
return f"{celsius}°C = {fahrenheit}°F"
elif "F to C" in input_str:
fahrenheit = float(input_str.split(":")[-1].strip())
celsius = (fahrenheit - 32) * 5 / 9
return f"{fahrenheit}°F = {celsius:.2f}°C"@agent.tool(name="greet", description="Greet someone by name")
def greet_person(name: str) -> str:
"""Custom greeting"""
return f"Hello, {name}! How can I assist you today?"# Listar ferramentas registradas
for tool_name, tool_desc in agent.get_tools().items():
print(f" - {tool_name}: {tool_desc}")
# Usar ferramenta via pergunta natural
answer = agent.run("What time is it now?", verbose=True)
answer = agent.run("Generate a random number between 1 and 100", verbose=True)
answer = agent.run("Convert 25 degrees Celsius to Fahrenheit", verbose=True)
answer = agent.run("Greet John", verbose=True)- Docstrings claras: Sempre documente o que a ferramenta faz
- Type hints: Use type hints para parâmetros e retorno
- Error handling: Trate erros adequadamente
- Formato de entrada: Documente formato esperado de parâmetros
- Retorno consistente: Sempre retorne string
Arquivo: react_agent_framework/examples/memory_demo.py
Sistema de memória v0.10.0 completamente refatorado:
- Chat Memory: Histórico de conversação (SQLite, in-memory)
- Knowledge Memory: Base de conhecimento para RAG (ChromaDB, FAISS)
# Memória básica (sem dependências extras)
python react_agent_framework/examples/memory_demo.py
# Com ChromaDB
pip install chromadb
python react_agent_framework/examples/memory_demo.py
# Com FAISS
pip install faiss-cpu sentence-transformers
python react_agent_framework/examples/memory_demo.pyfrom react_agent_framework.core.memory import SimpleChatMemory
# Criar memória de chat em memória
memory = SimpleChatMemory(
session_id="demo-session",
max_messages=100
)
# Adicionar mensagens
memory.add_message("Hello!", role="user")
memory.add_message("Hi there!", role="assistant")
# Buscar histórico
history = memory.get_history(limit=10)
for msg in history:
print(f"[{msg.role}]: {msg.content}")
# Limpar sessão
memory.clear()from react_agent_framework.core.memory import SQLiteChatMemory
# Criar memória persistente (SQLite)
memory = SQLiteChatMemory(
db_path="./chat_memory.db",
session_id="persistent-session",
max_messages=1000,
auto_vacuum=True
)
# Adicionar conversação
memory.add_message("What is Python?", role="user")
memory.add_message("Python is a programming language", role="assistant")
# Buscar histórico (persiste entre execuções!)
history = memory.get_history(session_id="persistent-session")
# Multi-sessão
memory.switch_session("another-session")
memory.add_message("Different conversation", role="user")
# Buscar por sessão
session1_history = memory.get_history(session_id="persistent-session")
session2_history = memory.get_history(session_id="another-session")from react_agent_framework.core.memory import ChromaKnowledgeMemory
# Criar base de conhecimento com ChromaDB
knowledge = ChromaKnowledgeMemory(
collection_name="python_docs",
persist_directory="./chroma_db"
)
# Adicionar documentos
knowledge.add_document(
content="Python is a high-level programming language known for simplicity",
metadata={"topic": "python", "type": "definition"}
)
knowledge.add_document(
content="FastAPI is a modern web framework for building APIs with Python",
metadata={"topic": "fastapi", "type": "framework"}
)
# Buscar semanticamente (RAG)
results = knowledge.search(
query="What web frameworks exist for Python?",
top_k=3,
filters={"type": "framework"}
)
for doc in results:
print(f"Score: {doc.score:.3f}")
print(f"Content: {doc.content}")
print(f"Metadata: {doc.metadata}")from react_agent_framework.core.memory import FAISSKnowledgeMemory
# Criar base de conhecimento com FAISS (rápido!)
knowledge = FAISSKnowledgeMemory(
index_path="./faiss_index",
embedding_model="all-MiniLM-L6-v2"
)
# Adicionar documentos
doc_ids = []
for i in range(100):
doc_id = knowledge.add_document(
content=f"Document {i} about AI and machine learning",
metadata={"doc_num": i}
)
doc_ids.append(doc_id)
# Busca rápida em grande volume
results = knowledge.search(
query="Tell me about AI",
top_k=5
)
# FAISS é otimizado para grandes volumes (>10k documentos)from react_agent_framework import ReactAgent
from react_agent_framework.core.memory import SQLiteChatMemory, ChromaKnowledgeMemory
# Criar agent com ambos os tipos de memória
chat_memory = SQLiteChatMemory(db_path="./agent_chat.db")
knowledge_memory = ChromaKnowledgeMemory(collection_name="agent_kb")
agent = ReactAgent(
name="Smart Assistant",
provider="gpt-4o-mini",
memory=chat_memory # Chat memory no agent
)
# Adicionar conhecimento manualmente
knowledge_memory.add_document(
"The React Agent Framework uses the ReAct pattern",
metadata={"source": "docs"}
)
# Usar ambos: chat guarda conversa, knowledge fornece contexto
def ask_with_context(question: str):
# 1. Buscar contexto relevante
context_docs = knowledge_memory.search(question, top_k=3)
context = "\n".join([d.content for d in context_docs])
# 2. Fazer pergunta com contexto
prompt = f"Context:\n{context}\n\nQuestion: {question}"
answer = agent.run(prompt)
# 3. Chat history é automaticamente salvo
return answer
answer = ask_with_context("What pattern does the framework use?")print("=" * 80)
print("QUANDO USAR CADA TIPO DE MEMÓRIA")
print("=" * 80)
print("\n📝 CHAT MEMORY (Histórico de Conversação)")
print("-" * 80)
print("USE QUANDO:")
print(" ✓ Precisa lembrar conversas anteriores")
print(" ✓ Quer manter contexto entre perguntas")
print(" ✓ Precisa de histórico sequencial")
print(" ✓ Trabalha com múltiplas sessões/usuários")
print("\nOPÇÕES:")
print(" • SimpleChatMemory: Teste/desenvolvimento (em memória)")
print(" • SQLiteChatMemory: Produção (persistente, sem deps extras)")
print("\nEXEMPLO:")
print(" Chatbot, assistente conversacional, suporte ao cliente")
print("\n\n📚 KNOWLEDGE MEMORY (Base de Conhecimento RAG)")
print("-" * 80)
print("USE QUANDO:")
print(" ✓ Precisa buscar informação relevante")
print(" ✓ Trabalha com documentos/conhecimento")
print(" ✓ Quer busca semântica (não exata)")
print(" ✓ Implementa RAG (Retrieval Augmented Generation)")
print("\nOPÇÕES:")
print(" • ChromaKnowledgeMemory: Até ~100k docs, recursos avançados")
print(" • FAISSKnowledgeMemory: +100k docs, máxima performance")
print("\nEXEMPLO:")
print(" Sistema de Q&A sobre docs, search engine, recomendação")
print("\n\n🔄 COMBINADO (Chat + Knowledge)")
print("-" * 80)
print("USE QUANDO:")
print(" ✓ Precisa de AMBOS: conversa + conhecimento")
print(" ✓ Quer contexto de docs em conversas")
print(" ✓ Implementa assistente com base de conhecimento")
print("\nCONFIGURAÇÃO:")
print(" • Chat Memory no agent (histórico)")
print(" • Knowledge Memory separado (contexto)")
print(" • Busca contexto → adiciona ao prompt → salva conversa")
print("\nEXEMPLO:")
print(" Assistente técnico com docs, suporte com KB, tutor com materiais")- Propósito: Histórico sequencial de mensagens
- Armazenamento: SQL (SQLite, PostgreSQL)
- Casos de uso: Chatbots, assistentes, suporte
- Características: Sessões, ordem cronológica, limites
- Propósito: Base de conhecimento para busca semântica
- Armazenamento: Vetores (ChromaDB, FAISS)
- Casos de uso: Q&A, documentação, recomendação
- Características: Embeddings, similarity search, metadata
# ❌ ANTIGO (v0.9.x)
from react_agent_framework.core.memory import ChromaMemory
memory = ChromaMemory() # Era usado para chat (incorreto!)
memory.add("Hello", role="user")
# ✅ NOVO (v0.10.0)
# Para CHAT (conversa):
from react_agent_framework.core.memory import SQLiteChatMemory
chat = SQLiteChatMemory(db_path="./chat.db")
chat.add_message("Hello", role="user")
# Para KNOWLEDGE (documentos/RAG):
from react_agent_framework.core.memory import ChromaKnowledgeMemory
knowledge = ChromaKnowledgeMemory(collection_name="docs")
knowledge.add_document("Python is a language", metadata={"topic": "python"})
results = knowledge.search("What is Python?", top_k=5)Use verbose=True para ver o raciocínio do agent:
answer = agent.run("Your question", verbose=True)
# Mostra: Thought → Action → Observation → ... → Final Answeragent.clear_history() # Limpa histórico de conversaçãotools = agent.get_tools()
for name, description in tools.items():
print(f"{name}: {description}")agent = ReactAgent(
provider="gpt-4o-mini",
temperature=0 # 0 = determinístico, 1 = criativo
)Solução: Configure as variáveis de ambiente
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."Solução: Instale as dependências do servidor
pip install mcp
npm install -g @modelcontextprotocol/server-filesystemSolução: Instale as dependências opcionais
pip install chromadb # Para ChromaKnowledgeMemory
pip install faiss-cpu sentence-transformers # Para FAISSKnowledgeMemorySolução: Veja o MIGRATION_GUIDE.md para atualizar para v0.10.0
- Leia a documentação completa: https://marcosf63.github.io/react-agent-framework/
- Explore os exemplos: Rode cada exemplo e veja o output
- Modifique os exemplos: Experimente diferentes parâmetros
- Crie seus próprios agents: Use os exemplos como base
- Contribua: https://github.com/marcosf63/react-agent-framework
Versão: 0.10.0 Última atualização: 2025-01-07