![CDATA[

Por que adotar o modelo de biblioteca pip?

Antes, o uso exigia a implantação via Docker. Agora, três perfis de consumo coexistem:

Aviso de segurança: Ferramentas de pentest exigem autoirzação explícita por escrito. A Decepticon inclui middleware de RoE (Rules of Engagement) e portões de segurança; a substituição de componentes críticos requer a variável DECEPTICON_ALLOW_SAFETY_OVERRIDES=1.

Três níveis de abstração para construir agentes

A arquitetura baseia‑se em langchain/langgraph, organizada em middlewares, ferramentas e prompts. É possível evoluir gradativamente:

Nível 1 – Fábricas padrão. As 16 funções de criação (recon, exploit, analyst etc.) geram agentes sem parâmetros obrigatórios:

from decepticon.agents.standard.exploit import create_exploit_agent

agente = create_exploit_agent()  # Configuração OSS padrão, dependências automáticas

Nível 2 – Fábrica com sobrescritas explícitas. Todas aceitam argumentos no estilo langchain, permitindo substituir ferramentas, a pilha de middlewares, o prompt ou injetar modelos customizados:

agente = create_exploit_agent(
    tools=[ferramenta_customizada],       # substituição total
    system_prompt="Você é um especialista em exploração...",
    llm=modelo_local,
    recursion_limit=350,
)

Nível 3 – Montagem direta com create_agent do langgraph. Ignoram‑se as fábricas e combinam‑se middlewares, back‑ends e ferramentas da Decepticon de forma granular — caminho indicado para prdoutos comerciais.

Construindo plugins com o decepticon‑sdk

O SDK exporta apenas a camada de contrato (decepticon-core) e fornece CLI e fakes para desenvolvimento ágil.

pip install "decepticon-sdk[testing]"   # inclui FakeBackend, FakeLLM, FakeSandbox

Scaffolding de plugin. O SDK suporta seis tipos (tool, middleware, agent, callback, skill, prompt). Basta um comando:

decepticon-sdk plugin new \
    --kind=middleware \
    --name=audit-logger \
    --path=./audit-logger

Protocolo e entry-points. Para um middleware de auditoria, implementa‑se a interface MiddlewareProtocol e declara‑se no pyproject.toml o grupo [project.entry-points."decepticon.middleware"]. A descoberta acontece automaticamente após a instalação do wheel.

Testes com fakes. O módulo decepticon_sdk.testing oferece implementações em memória para todos os contratos. Assim, plugins podem ser testados sem sandbox real ou LiteLLM.

Registrando papéis customizados e orquestradores

Para publicar um tipo de agente fora dos 16 nativos:

• RoleRegistry.register("apt", slots={"recon", "exploit"}, skill_source_path="...") – torna o papel "apt" um cidadão de primeira classe, reconhecido pelas fábricas de LLM e montadores de middleware. A chamada é idempotente.
• build_middleware(slots=...) – ao declarar explicitamente os slots para o papel personalizado, reutiliza‑se o sistema de encaixe e os portões de segurança. A omissão de slots para funções desconhecidas gera KeyError, evitando falhas silenciosas.

Em cenários multi‑tenant, make_agent_backend(extra_routes=...) monta árvores de ativos isoladas por locatário usando prefixo mais longo.

Portões de segurança: a linha de defesa do ecossistema

O carregamento de plugins baseia‑se em entry points (decepticon.tools, decepticon.middleware etc.) e inclui barreiras protetivas:

• Substituir ou desabilitar slots críticos (engagement-context, sandbox-notification) ou ferramentas como ask_user_question durante a construção do agente dispara SafetyOverrideViolation.
• Autores de plugins podem adicionar declarações de segurança (SafetyDeclaration), mas nunca remover as proteções originais.
• Em produção, DECEPTICON_STRICT_REGISTRY=1 transforma conflitos de entrada em erro imediato.

Lista de partida rápida