English 中文 العربية 日本語 Português

Pi Agent: Event System & Command Registration

Última atualização: 2026-08-31

--- title: "Sistema de Eventos e Registro de Comandos" description: "Domine a arquitetura orientada a eventos do Pi Agent e o mecanismo de registro de comandos para tratamento personalizado de eventos e extensoes de comandos." order: 16 lang: pt-br

O sistema de eventos transforma o Agent de "você pergunta, ele responde" em verdadeira comunicação bidirecional.

1. Visão Geral do Sistema de Eventos

Pi Agent usa uma arquitetura orientada a eventos:

TEXT 📖 Somente leitura 
Event Flow
Trigger Source → Event Bus → Handler
  User input      Dispatch/route   Tool calls
  Tool return     Filter/sort      UI updates
  Timer           Priority sort    Logging
  External msg    Error routing    Notifications

2. Eventos Integrados

Evento Gatilho Dados
on_chat_start Conversa começa session_id
on_chat_end Conversa termina session_id, summary
on_user_message Usuário envia mensagem message
on_agent_response Agent responde response
on_tool_call Ferramenta chamada tool_name, params
on_tool_result Ferramenta retorna resultado tool_name, result
on_error Erro ocorre error, context
on_model_switch Modelo trocado old_model, new_model
on_context_overflow Overflow de contexto size, limit

3. Escuta de Eventos

(1) Estilo Decorador

PYTHON 
from pi_agent import Agent

agent = Agent(name="monitored")

@agent.on("tool_call")
def log_tool_call(event):
    print(f"Tool called: {event.tool_name}({event.params})")

@agent.on("error")
def handle_error(event):
    print(f"Error: {event.error}")
    with open("error_log.txt", "a") as f:
        f.write(f"{event.error}\n")

@agent.on("agent_response")
def log_response(event):
    print(f"Token usage: {event.response.usage}")

(2) Estilo Classe

PYTHON 
from pi_agent import Agent, EventHandler

class MyHandler(EventHandler):
    def on_tool_call(self, event):
        print(f"Tool: {event.tool_name}")

    def on_tool_result(self, event):
        print(f"Result: {event.result}")

    def on_error(self, event):
        print(f"Error: {event.error}")

agent = Agent(name="monitored", event_handler=MyHandler())

4. Eventos Personalizados

(1) Definir Evento

PYTHON 
from pi_agent import Event

class DeployEvent(Event):
    name = "deploy"
    fields = ["environment", "status", "url"]

(2) Emitir Evento

PYTHON 
agent.emit("deploy", {
    "environment": "production",
    "status": "success",
    "url": "https://myapp.example.com"
})

(3) Escutar Evento Personalizado

PYTHON 
@agent.on("deploy")
def on_deploy(event):
    if event.status == "success":
        send_notification(f"Deploy succeeded: {event.url}")

5. Registro de Comandos

(1) Registrar Comandos Interativos

PYTHON 
from pi_agent import Agent

agent = Agent(name="custom_cmd")

@agent.command("/deploy", description="Deploy project to specified environment")
def deploy_cmd(args: str):
    env = args.strip() or "staging"
    result = agent.run(f"Deploy current project to {env}")
    print(result)

@agent.command("/review", description="Review code in specified file")
def review_cmd(args: str):
    filename = args.strip()
    result = agent.run(skill="code_review", file=filename)
    print(result)

@agent.command("/cost", description="Show token usage stats for current session")
def cost_cmd(args: str):
    usage = agent.session.get_usage()
    print(f"Token usage: {usage.total_tokens}")
    print(f"Estimated cost: ${usage.estimated_cost:.4f}")

6. Filtros de Eventos

(1) Filtragem Condicional

PYTHON 
@agent.on("tool_call", filter=lambda e: e.tool_name == "shell")
def log_shell_calls(event):
    print(f"Shell command: {event.params.get('cmd')}")

(2) Prioridade

PYTHON 
@agent.on("error", priority=10)
def critical_error(event):
    send_alert(f"Critical error: {event.error}")

@agent.on("error", priority=1)
def log_error(event):
    with open("errors.log", "a") as f:
        f.write(f"{event.error}\n")

❓ Perguntas Frequentes

P: Handlers de eventos podem modificar dados do evento? R: Sim, mas é recomendado apenas ler para evitar efeitos colaterais. Dados modificados são visíveis para handlers subsequentes. P: Tratamento de eventos síncrono ou assíncrono? R: Padrão síncrono, executado por prioridade. Use async_handler=True para handlers assíncronos. P: Comandos vs comandos com barra? R: Comandos são extensões personalizadas via @agent.command(). Comandos com barra são comandos integrados do modo interativo (/help, /exit). Mesmo formato, fontes diferentes.

❓ Resumo

📝 Exercícios

  1. Básico (Dificuldade: ⭐): Escute eventos tool_call, registre todas as chamadas de ferramentas em um arquivo.
  2. Intermediário (Dificuldade: ⭐⭐): Crie um comando /summarize que gere um resumo da sessão.
  3. Avançado (Dificuldade: ⭐⭐⭐): Implemente um pipeline de deploy orientado a eventos: revisão de código → teste → deploy, cada estágio acionado por eventos.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%