[PITCH] TAgent: Quando você está farto da complexidade desnecessária para criar agentes · VictorTavernari

Estava cansado de frameworks gigantescos só para fazer um agente resolver problemas pontuais. Sério, por que preciso de 50 dependências e 200 linhas de boilerplate só para fazer uma automação simples?

Então comecei a explorar uma abordagem mais "indie" - criar um framework de agentes que seja direto ao ponto, menos verboso e que não me obrigue a ler documentação por horas antes de conseguir fazer algo útil.

gif

O que é o TAgent?

O TAgent é um framework minimalista para criar agentes AI que seguem uma arquitetura inspirada no Redux. A ideia é simples: estado centralizado, ações controladas por uma máquina de estados, e structured outputs em vez de function calling (que nem todo modelo suporta direito).

from tagent import run_agent

# Isso é literalmente tudo que você precisa para começar
result = run_agent(
    goal="Traduza 'Olá mundo' para inglês",
    model="gpt-4o-mini", 
    max_iterations=3
)

Como funciona por baixo do capô?

Máquina de Estados Determinística

Em vez de deixar o LLM fazer o que quiser, o agente segue um fluxo controlado:

INITIAL → PLAN → EXECUTE → EVALUATE → (loop até atingir o objetivo)

Cada transição é validada, evitando loops infinitos e comportamentos imprevisíveis.

Structured Outputs

Nada de function calling. O LLM retorna JSON estruturado que é validado com Pydantic:

{
  "action": "execute",
  "params": {"tool": "search", "args": {"query": "python"}},
  "reasoning": "Preciso buscar informações sobre Python"
}

Sistema de Fallback Inteligente

Se uma ferramenta não existe, o agente usa o próprio conhecimento do LLM como fallback. Sem crashes, sem erros - apenas funciona.

Ferramentas e Extensibilidade

Por enquanto não tem ferramentas padrão (mantendo o minimalismo), mas já estou trabalhando em adapters para aceitar tools do:

CrewAI
LangChain
Model Context Protocol (MCP)

A ideia é que você possa aproveitar ecossistemas existentes sem ficar preso a eles.

Exemplo Prático

Aqui está um agente que extrai e traduz artigos do TabNews:

def extract_tabnews_articles(state, args):
    """Busca artigos recentes do TabNews via RSS"""
    response = requests.get("https://www.tabnews.com.br/recentes/rss")
    # ... processa XML e retorna lista de artigos
    return ("articles", articles_list)

def translate(state, args):
    """Traduz texto usando LLM direto"""
    text = args.get("text", "")
    target = args.get("target_language", "")
    # ... chama LLM para traduzir
    return ("translation", {"translation": result})

# Executa o agente
result = run_agent(
    goal="Pegue 1 artigo do TabNews, carregue o conteúdo, resuma e traduza para chinês",
    model="gpt-4o-mini",
    tools={
        "extract_tabnews_articles": extract_tabnews_articles,
        "load_url_content": load_url_content, 
        "translate": translate
    },
    max_iterations=15
)

O agente planeja, executa as ferramentas na ordem correta, e entrega o resultado estruturado.

Por que Redux para Agentes?

Estado Previsível: Sempre sabemos o que está acontecendo
Debug Friendly: Todo passo é logado e pode ser inspecionado
Composição: Ferramentas são funções puras, fáceis de testar
Extensível: Adicionar novas ações é trivial

Performance e Modelos

Funciona com qualquer modelo via LiteLLM:

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude)
Ollama local
OpenRouter
E mais...

Cada tipo de ação pode usar um modelo diferente (planejamento com GPT-4, execução com modelo mais barato).

Terminal Retrô

Porque vida é curta demais para UIs sem personalidade:

▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓                 T-AGENT v0.5.0 STARTING                  ▓ 
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[-] [12:34:56] INIT: Goal: Translate hello world to Chinese
[#] [12:34:57] PLAN: Generating strategic plan...
[>] [12:34:58] EXECUTE: Using LLM fallback for translation
[+] [12:34:59] SUCCESS: Translation completed!

Roadmap

Adapters para CrewAI/LangChain/MCP tools
Sistema de memória persistente
Ferramentas padrão (web search, file operations)
Interface web opcional
Multiagent orchestration

Experimente Você Mesmo

git clone https://github.com/tavernari/tagent
cd tagent
pip install -r requirements.txt

# Rode o exemplo do TabNews
# configure seu env e escolha o modelo.. uso openrouter
python examples/tab_news_analyzer/tabnews_code_example.py

Conclusão

O TAgent não vai resolver todos os problemas do mundo, mas se você quer criar agentes sem dor de cabeça e com código que você consegue entender 6 meses depois, talvez valha a pena dar uma olhada.

O framework é pequeno (menos de 2000 linhas), focado, e cada componente tem uma responsabilidade clara. Às vezes simples é melhor.

Repo: https://github.com/tavernari/tagent
Licença: MIT

Se você chegou até aqui e achou interessante, deixa uma estrela no GitHub. Se não gostou, pode abrir uma issue reclamando - feedback é sempre bem-vindo.