Agentes

O que e um agente

Um agente e uma persona de IA especializada em resolver um problema concreto. Ele tem um nome, um modelo LLM, instruções próprias (CLAUDE.md), guardrails, skills e um conjunto de MCPs que define quais sistemas externos ele pode consultar ou alterar. Cada agente vive dentro de um tenant — e só e visto pelos usuários daquele tenant.

Anatomia de um AgentDoc

// Shape simplificado guardado em <slug>__agents
{
  _id: "bot-suporte",          // slug único dentro do tenant
  name: "Bot Suporte",
  emoji: "🤖",
  description: "Atende dúvidas de planos e 2a via de faturas",
  model: "claude-sonnet-4-5",
  status: "active",            // "paused" | "error" | "creating"
  claudeMd: "...",             // instruções principais
  coreFiles: {
    identity: "...",
    soul: "...",
    tools: "...",
    agents: "...",
    user: "...",
    memory: "..."
  },
  guardrails: {
    maxJobs: 10,
    maxConsecutiveMessages: 5,
    allowedChannels: [],
    customRules: []
  },
  mcpServers: { /* ver doc de MCP */ },
  envVars: { /* chaves para os MCPs */ },
  tenantSlug: "acme",
  createdAt: "...", updatedAt: "...", createdBy: "<userId>"
}

Como o agente e executado

A execução e on-demand, uma mensagem por vez. O core chama invokeAgent(tenantSlug, agent, message), que: (1) monta um sessionDir isolado por (tenantSlug, slug), (2) escreve .mcp.json só com os MCPs autorizados pelo plano, (3) escreve CLAUDE.md a partir de claudeMd + coreFiles e (4) dispara claude --print com o modelo configurado. O resultado volta em um único turno, ou em streaming via SSE quando você chama o endpoint /chat/:id/stream.

Modelos recomendados

Ciclo de vida

• creating: criado, aguardando setup inicial (primeiro chat / instalacao de MCP)
• active: recebendo mensagens e executando tarefas
• paused: existente mas não aceita invocacoes; preserva histórico e configuração
• error: detectamos falha repetida — logs em <slug>__agent_events com causa

Guardrails

Guardrails definem limites rigidos para o agente. Todos são opcionais, mas recomendamos configurar ao menos maxIterations e timeoutSeconds para evitar loops longos.

• maxIterations: teto de ciclos think/act em uma mesma execução
• timeoutSeconds: tempo máximo por invocacao
• requireApprovalFor: ações que exigem aprovação humana antes de disparar (ex: "enviar email externo")
• forbiddenTopics: assuntos que o agente deve recusar com mensagem padronizada
• allowedChannels: lista branca de canais onde ele pode atuar

Diagnostico automático

Quando um agente comeca a falhar (crashes, injection attempts, queda de volume), o próprio core gera um diagnostico — heuristico rápido via GET /agents/:id/diagnose, ou aprofundado com LLM via POST /agents/:id/diagnose. A resposta traz healthScore 0-100, summary e lista de issues priorizadas por severidade.