Examples

💡 Examples

Exemplos práticos de uso do Mangaba AI.

---

Exemplos Básicos

1. Agente Simples

from mangaba import Agent
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

llm_config = LLMConfig(
    provider="google",
    api_key="KEY",
    model="gemini-2.5-flash",
    temperature=0.7,
    max_tokens=4096,
)

llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

agent = Agent(
    role="Professor",
    goal="Explicar conceitos de forma clara",
    backstory="Professor experiente com didática excepcional",
    llm=llm,
)

print(agent.execute_task("Explique o que é machine learning para um iniciante"))

2. Multi-Agent Crew

from mangaba import Agent, Task, Crew, Process
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

# Agents
researcher = Agent(
    role="Researcher", goal="Find data", backstory="Expert researcher", llm=llm,
)
writer = Agent(
    role="Writer", goal="Write reports", backstory="Professional writer", llm=llm,
)

# Tasks
research = Task(
    description="Research {topic} trends",
    expected_output="List of findings",
    agent=researcher,
)
report = Task(
    description="Write comprehensive report",
    expected_output="Markdown report",
    agent=writer,
    context=[research],
)

# Crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research, report],
    process=Process.SEQUENTIAL,
)

result = crew.kickoff({"topic": "AI agents"})
print(result)

3. Agent com Tools

from mangaba import Agent, BaseTool
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client
from mangaba.tools.math_tools import CalculatorTool

llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

class WeatherTool(BaseTool):
    name = "weather"
    description = "Get current weather for a city"

    def _run(self, city: str) -> str:
        # Simulação
        return f"Weather in {city}: 25°C, Sunny"

agent = Agent(
    role="Travel Planner",
    goal="Plan trips based on weather",
    backstory="Expert travel agent",
    tools=[WeatherTool(), CalculatorTool()],
    llm=llm,
)

print(agent.execute_task("What's the weather in São Paulo and Tokyo?"))

4. RAG Pipeline

from mangaba.rag import TextLoader, RecursiveTextSplitter, Retriever, RAGChain
from mangaba.embeddings import OpenAIEmbedding
from mangaba.vectorstores import InMemoryVectorStore
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

# Load & split
loader = TextLoader("docs/knowledge.txt")
docs = loader.load()
splitter = RecursiveTextSplitter(chunk_size=500)
chunks = splitter.split_documents(docs)

# Setup
embedding = OpenAIEmbedding(api_key="KEY")
store = InMemoryVectorStore()
retriever = Retriever(embedding=embedding, store=store)
retriever.add_documents(chunks)

# RAG Chain
llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)
chain = RAGChain(llm=llm, retriever=retriever, top_k=3)

answer = chain.ask("How do I configure the system?")
print(answer)

5. Vector Store com Redis

from mangaba.vectorstores import RedisVectorStore
from mangaba.embeddings import OpenAIEmbedding

embed = OpenAIEmbedding(api_key="KEY")
store = RedisVectorStore(
    url="redis://localhost:6379",
    index_name="my_docs",
    vector_dimensions=1536,
)

texts = ["Python tutorial", "JavaScript guide", "Rust fundamentals"]
embeddings = embed.embed_batch(texts)

ids = store.add(texts, embeddings, [{"lang": "python"}, {"lang": "js"}, {"lang": "rust"}])
results = store.search(embed.embed_text("programming language"), top_k=2)

for r in results:
    print(f"{r['content']} (score: {r['score']:.3f})")

store.close()

6. Vector Store com PostgreSQL

from mangaba.vectorstores import PostgresVectorStore

store = PostgresVectorStore(
    url="postgresql://postgres:minhasenha@localhost:5432/mangaba",
    table_name="embeddings",
    vector_dimensions=1536,
)

store.add(texts, embeddings)
results = store.search(query_embedding, top_k=5)
store.close()

7. Workflow Pipeline

from mangaba import Pipeline, Stage, ParallelStage, ConditionalStage

pipeline = Pipeline(stages=[
    Stage("research", [research_task]),
    ParallelStage("analysis", [financial_task, technical_task]),
    ConditionalStage("expand",
        condition=lambda inputs: inputs.get("deep", False),
        if_true=Stage("deep", [deep_analysis_task]),
        if_false=Stage("quick", [quick_analysis_task]),
    ),
    Stage("report", [report_task]),
])

result = pipeline.run({"topic": "AI", "deep": True})
for stage in result.stages:
    print(f"{stage.stage_name}: {stage.duration:.2f}s")

8. Guardrails & Output Parsers

from mangaba import Agent
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client
from mangaba.core.guardrails import LengthGuardrail, ContentFilterGuardrail
from mangaba.core.output_parsers import PydanticOutputParser
from pydantic import BaseModel

llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

class AnalysisSchema(BaseModel):
    title: str
    points: list[str]
    conclusion: str

parser = PydanticOutputParser(model=AnalysisSchema)

agent = Agent(
    role="Analyst",
    goal="Provide structured analysis",
    backstory="Expert analyst",
    guardrails=[
        LengthGuardrail(min_length=100),
        ContentFilterGuardrail(),
    ],
    output_parser=parser,
    llm=llm,
)

result = agent.execute_task("Analyze the AI market")
print(result)  # AnalysisSchema instance

9. Events & Observability

from mangaba.core.events import EventBus, Event, EventType, BaseCallback
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

class Logger(BaseCallback):
    def on_event(self, event: Event) -> None:
        print(f"[{event.event_type.value}] {event.data}")

EventBus.register(Logger())

# Agora cada ação do agent emite eventos
agent = Agent(role="...", goal="...", backstory="...", llm=llm)
agent.execute_task("Do something")
# [agent_start] {...}
# [tool_start] {...}
# [react_observation] {...}
# [agent_end] {...}

10. @tool Decorator

from mangaba import Agent, tool
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

@tool
def search(query: str, max_results: int = 5) -> str:
    """Search the web for information."""
    results = duckduckgo_search(query, limit=max_results)
    return "\n".join(f"- {r['title']}" for r in results)

@tool
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression, {"__builtins__": {}}, {}))

agent = Agent(
    role="Researcher",
    goal="Research and calculate",
    backstory="Expert researcher",
    tools=[search, calculate],
    llm=llm,
)

result = agent.execute_task("Search for GDP of Brazil and calculate 10% of it")

---

Exemplos Avançados

Hierarchical Crew

crew = Crew(
    agents=[manager, worker1, worker2, worker3],
    tasks=[task1, task2, task3],
    process=Process.HIERARCHICAL,  # Manager delega e revisa
)
result = crew.kickoff()

Consensual Crew

crew = Crew(
    agents=[expert1, expert2, expert3],
    tasks=[analysis_task],
    process=Process.CONSENSUAL,  # Todos opinam
)
result = crew.kickoff()

Parallel Crew

crew = Crew(
    agents=[agent1, agent2, agent3],
    tasks=[independent1, independent2, independent3],
    process=Process.PARALLEL,  # Concorrente
)
result = crew.kickoff()

Memory Persistence

from mangaba.memory import LongTermMemory
from mangaba.embeddings import OpenAIEmbedding
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

llm_config = LLMConfig(provider="google", api_key="KEY", model="gemini-2.5-flash")
llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

memory = LongTermMemory(
    db_path="./agent_memory.db",
    embedding=OpenAIEmbedding(api_key="KEY"),
    enable_vector_search=True,
)

agent = Agent(
    role="Assistant",
    goal="Remember context",
    backstory="Helpful assistant with memory",
    memory=memory,
    llm=llm,
)

# Memórias persistem entre execuções
agent.execute_task("My name is João and I like Python")
# ... reiniciar app ...
agent.execute_task("What is my name?")  # "João"