Skip to content

Core Components

Jump to bottom
Ysrael edited this page May 10, 2026 · 1 revision

🧩 Core Components

Documentação dos componentes centrais do Mangaba AI: Agent, Task e Crew.

Agent

O Agent é a unidade fundamental de inteligência. Cada agent possui:

  • Role — Papel/função do agent
  • Goal — Objetivo principal
  • Backstory — Contexto/background
  • Tools — Ferramentas disponíveis
  • Memory — Sistema de memória
  • ReAct Engine — Loop de raciocínio Thought → Action → Observation

Criação

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

# Configuração via LLMConfig
llm_config = LLMConfig(
    provider="google",
    model="gemini-2.5-flash",
    api_key="sua-api-key",
    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="Senior Data Analyst",
    goal="Analyze market trends and provide actionable insights",
    backstory="Expert in financial markets with 15 years of experience in quantitative analysis",
    llm=llm,                          # LLMClient instance
    tools=[],                         # List[BaseTool]
    verbose=False,                    # Log detalhado
    max_iterations=15,                # Máximo de iterações ReAct
    max_retry_on_error=3,             # Retries em caso de erro
    allow_delegation=True,            # Permitir delegação
    memory=None,                      # BaseMemory instance
    memory_config=None,               # MemoryConfig
    guardrails=[],                    # List[BaseGuardrail]
    output_parser=None,               # BaseOutputParser
    step_callback=None,               # Callback por step
)

Parâmetros

Parâmetro Tipo Default Descrição
role str required Papel do agent
goal str required Objetivo principal
backstory str required Contexto/background
llm LLMClient None Cliente LLM ou string provider
tools List[BaseTool] [] Ferramentas disponíveis
verbose bool False Log detalhado
max_iterations int 15 Máximo iterações ReAct
max_retry_on_error int 3 Retries em erro
allow_delegation bool True Delegar tasks a peers
memory BaseMemory None Sistema de memória
guardrails List[BaseGuardrail] [] Validadores de output
output_parser BaseOutputParser None Parser de output

Métodos

Método Descrição
execute_task(task: str, context: str?) → str Executa uma task via loop ReAct
connect_to(other: Agent) → None Conecta a outro agent para delegação
delegate(peer_id: str, task: str, context: str?) → str Delega task a peer

Exemplo

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,
)

agent = Agent(
    role="Researcher",
    goal="Find accurate information",
    backstory="Expert researcher",
    llm=llm,
)

result = agent.execute_task("What are the top 3 AI trends for 2026?")
print(result)

Task

Uma Task é uma unidade de trabalho atribuída a um Agent.

Criação

from mangaba import Task

task = Task(
    description="Research {topic} and produce a report",
    expected_output="A detailed markdown report with findings",
    agent=researcher,               # Agent instance
    context=[],                     # List[Task] — dependências
    tools=[],                       # Tools extras para esta task
    output_file="output/report.md", # Salvar em arquivo
    callback=None,                  # Callback ao completar
    async_execution=False,          # Execução assíncrona
    human_input=False,              # Requer input humano
    guardrails=[],                  # Guardrails específicos
    output_parser=None,             # Parser específico
    retry_on_failure=0,             # Retries
)

Parâmetros

Parâmetro Tipo Default Descrição
description str required Descrição da task (suporta templates {var})
expected_output str required Descrição do output esperado
agent Agent required Agent responsável
context List[Task] [] Tasks anteriores cujo output é contexto
output_file str None Path para salvar output
callback Callable None Callback ao completar
async_execution bool False Execução assíncrona
human_input bool False Requer input humano
retry_on_failure int 0 Número de retries

Métodos

Método Descrição
execute(inputs: dict?) → TaskOutput Executa task sincronamente
aexecute(inputs: dict?) → TaskOutput Executa task assincronamente

TaskOutput

output = task.execute({"topic": "AI trends"})
print(output.result)         # Resultado em texto
print(output.description)    # Descrição da task
print(output.agent)          # Nome do agent
print(output.success)        # bool — sucesso?
print(output.timestamp)      # ISO timestamp

Templates

Tasks suportam substituição de variáveis:

task = Task(
    description="Write a report about {topic} for {audience}",
    expected_output="Report in markdown",
    agent=writer,
)

# As variáveis são substituídas ao executar
output = task.execute({"topic": "AI", "audience": "developers"})
# → "Write a report about AI for developers"

Crew

Crew orquestra múltiplos agents trabalhando em múltiplas tasks.

Criação

from mangaba import Crew, Process

crew = Crew(
    agents=[researcher, analyst, writer],
    tasks=[research_task, analyze_task, write_task],
    process=Process.SEQUENTIAL,     # Modo de execução
    verbose=True,
)

Modos de Processo

Modo Descrição
Process.SEQUENTIAL Tasks executam uma após outra, em ordem
Process.HIERARCHICAL Manager agent delega e revisa tasks dos workers
Process.PARALLEL Tasks independentes executam concorrentemente (asyncio)
Process.CONSENSUAL Todos os agents executam cada task; resultados são sintetizados

Parâmetros

Parâmetro Tipo Default Descrição
agents List[Agent] required Agents da crew
tasks List[Task] required Tasks a executar
process Process SEQUENTIAL Modo de execução
verbose bool False Log detalhado
max_rpm int None Máximo requests/minuto
memory Any None Memória compartilhada

Métodos

Método Descrição
kickoff(inputs: dict?) → CrewOutput Executa a crew e retorna resultado

CrewOutput

result = crew.kickoff({"topic": "AI"})
print(result.final_output)     # Output da última task
print(result.tasks_outputs)    # List[TaskOutput]
print(result.process)          # Process enum
print(result.duration)         # Tempo em segundos
print(result.crew_id)          # ID único
print(result.timestamp)        # ISO timestamp

Exemplo Hierarchical

crew = Crew(
    agents=[manager, researcher1, researcher2, writer],
    tasks=[research1, research2, write_report],
    process=Process.HIERARCHICAL,  # Manager delega e revisa
    verbose=True,
)
result = crew.kickoff()

Exemplo Consensual

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

Exemplo Parallel

crew = Crew(
    agents=[agent1, agent2, agent3],
    tasks=[independent_task1, independent_task2, independent_task3],
    process=Process.PARALLEL,      # Executa concorrentemente
    verbose=True,
)
result = crew.kickoff()

Task Dependencies

Tasks podem depender de outras tasks via context:

research = Task(
    description="Research AI trends",
    expected_output="List of trends",
    agent=researcher,
)

analysis = Task(
    description="Analyze the research findings",
    expected_output="Analysis report",
    agent=analyst,
    context=[research],  # Recebe output de research como contexto
)

# O output de research é automaticamente injetado no prompt de analysis

Agent Delegation

Agents podem delegar tasks entre si:

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,
)

manager = Agent(role="Manager", goal="...", backstory="...", llm=llm)
worker = Agent(role="Worker", goal="...", backstory="...", llm=llm)

# Conectar agents
manager.connect_to(worker)

# Delegar
result = manager.delegate(worker.agent_id, "Research this topic")

Nota: O Crew conecta automaticamente todos os agents entre si.

🗺️ Navigation

Clone this wiki locally