Módulo 4.2 — Primeiro agente

📦 Estrutura mínima — Subclasse de Agent

Todo agente Cerebrum começa como subclasse de cerebrum.Agent com um método run(query) obrigatório. Esse método recebe a query do usuário e devolve a resposta. Tudo o que o agente faz dentro do run usa syscalls do SDK.

from cerebrum import Agent, LLMCall

class EchoAgent(Agent):
    name = "echo"
    description = "Devolve a query passando por um LLM"

    def run(self, query: str) -> str:
        return LLMCall(model="gpt-4o-mini", prompt=query).execute()

💡 Dica

Comece com agente de 3 linhas. Não tente fazer multi-step na primeira tentativa — você vai querer entender uma syscall antes de orquestrar dez.

🔧 Registrar tools — Decorator @tool

Tools são funções Python expostas ao Tool Manager via decorator @tool. Uma vez registrada, fica disponível para qualquer agente fazer ToolCall. Padronize tools entre projetos — evite escrever o mesmo wrapper de HTTP cinco vezes.

from cerebrum import tool, ToolCall

@tool(name="get_weather", description="Retorna clima da cidade")
def get_weather(city: str) -> dict:
    import requests
    return requests.get(f"https://wttr.in/{city}?format=j1").json()

# Em outro lugar do agente:
data = ToolCall(name="get_weather", args={"city": "São Paulo"}).execute()

📊 Boas práticas

Tool deve ter name descritivo (vai virar prompt para o LLM escolher)
description objetiva (LLM lê para decidir quando usar)
Argumentos com type hints (Cerebrum gera schema JSON automaticamente)
Retorno serializável (dict/list/str/int — nada de objeto Python custom)

💾 Memory/Storage — Onde guardar estado

Estado de curto prazo (working set da sessão) vai para Memory. Estado durável (logs, datasets, embeddings) vai para Storage. Erro clássico: salvar conhecimento permanente em Memory e perder no primeiro restart.

from cerebrum import MemoryRead, MemoryWrite, StorageRead, StorageWrite

# Memory: rápido, por agente, some no restart
MemoryWrite(key="last_query", value=query).execute()
prev = MemoryRead(key="last_query").execute()

# Storage: persistente, compartilhável
StorageWrite(path="research/aios.md", content=summary).execute()
content = StorageRead(path="research/aios.md").execute()

💡 Regra de polegar

Se precisa sobreviver a um restart, é Storage. Se é cache da sessão atual, é Memory. Em dúvida, use Storage — perder dado é pior que ser mais lento.

▶️ Submeter query — Ciclo completo

Com agente definido, basta instanciar e chamar run. Em produção, normalmente isso vira CLI, endpoint HTTP ou hook do Terminal/Web UI. Em dev, um script Python já basta.

# Script de teste
from my_agent import EchoAgent

agent = EchoAgent()
result = agent.run("Explique AIOS em uma frase.")
print(result)

📊 Modos de execução

One-shot — uma query, uma resposta, agente morre
Long-running — agente mantém estado, recebe N queries
Streaming — resposta vem token a token
Background — agente roda agendado sem usuário esperando

📝 Logging e debug — strace do agente

Ative log verbose no kernel. Cada syscall vira uma linha de log com timestamp, agente origem, módulo destino e payload. É o equivalente ao strace do Linux — sem ele, você adivinha o que está acontecendo.

# Subir kernel com log verbose
$ AIOS_LOG_LEVEL=DEBUG python -m aios.kernel | tee kernel.log

# Log típico
[12:01:03] AGENT=echo SYSCALL=LLMCall MODEL=gpt-4o-mini TOKENS=42
[12:01:04] AGENT=echo SYSCALL=MemoryWrite KEY=last_query
[12:01:04] AGENT=echo SYSCALL=ToolCall NAME=get_weather ARGS={"city":"SP"}

💡 Quando log não basta

Para investigar comportamento sutil, integre tracing distribuído (OpenTelemetry). Cada syscall vira um span; visualizar no Jaeger mostra cadeias de execução completas.

🚢 Empacotar e publicar — Hub mode

Para distribuir o agente, organize pasta com manifest (metadados), código e tools. Publique no agent hub — qualquer usuário com Cerebrum instala com 1 comando.

# Estrutura típica
my-research-agent/
├── manifest.yaml      # name, version, description, deps
├── agent.py           # subclasse de Agent
├── tools.py           # @tool decorators
└── README.md          # uso

# Publicar
$ cerebrum hub publish my-research-agent

# Outros usuários instalam
$ cerebrum hub install my-research-agent
$ cerebrum run my-research-agent "minha query"

💡 Versione cedo

Use semver desde o primeiro publish. Quando seu agente virar dependência de outros agentes, breaking change sem bump de major causa caos.

✅ Resumo do Módulo

✓

Subclasse de Agent + run(). Esqueleto mínimo de qualquer agente.

✓

@tool registra função no kernel. Reuso para outros agentes.

✓

Memory vs Storage. Curto prazo vs durável.

✓

Logs são o strace. Sem log verbose, debug é chute.

✓

Hub publish/install é trivial. Distribuição com 1 comando.

Próxima trilha:

Trilha 5 — 🤖 Agentes em produção. Frameworks suportados (AutoGen, OpenAGI) e casos práticos.

← Anterior: 4.1 Próxima: Trilha 5 →