Ganchos de agente

O Agent Hooks ainda não está disponível para .NET. Use o middleware do agente, a aprovação da ferramenta e a segurança do agente para adicionar controles de runtime aos agentes de .NET.

Agent Hooks é experimental em Python. A fábrica emite um ExperimentalWarning quando usado pela primeira vez e sua API pode ser alterada antes da disponibilidade geral.

Quando usar ganchos de agente

Use os Ganchos do Agente quando os controles desenvolvidos independentemente precisarem de um contrato compartilhado e exequível na entrada do agente, chamadas de modelo, chamadas de ferramenta e saída final.

O que o Agent Framework impõe

Quando você adiciona o Agent Hooks a um agente, o Agent Framework aplica um limite de imposição coordenado entre execuções de agente, chamadas de modelo e chamadas de ferramenta. O runtime fornece as seguintes garantias:

• Falha ao fechar: Uma negação bloqueia a ação protegida. Contextos inválidos, veredictos inválidos, falhas de interceptador e falhas de imposição não ignoram silenciosamente os controles.
• Transformar write-back: Uma transformação altera as mensagens nativas, os argumentos da ferramenta, os resultados da ferramenta ou a resposta final que a execução realmente usa. Se uma transformação não puder ser aplicada, a execução falhará.
• Streaming em buffer: Nenhuma atualização de resposta atinge o chamador até que a resposta completa do modelo e a saída final passem seus pontos de interceptação.
• Persistência fechada por veredicto: Persistência aguarda o veredicto que o cobre. A persistência de pós-execução padrão aguarda output; a persistência do histórico de chamadas por serviço espera por cada post_model_call.
• Concluir a instalação do pacote: As partes de agente, chat e função são instaladas como uma unidade, portanto, um limite de imposição incompleto não pode ser configurado acidentalmente.

O contrato é cooperativo em vez de um limite de isolamento de processo. Interceptores são executados no processo de host e recebem o conteúdo necessário para tomar decisões. Registre apenas interceptores de sua confiança.

Instalar ganchos de agente

Instale o extra opcional agent-hooks para o pacote principal:

pip install "agent-framework-core[agent-hooks]"

Se você usar uv:

uv add "agent-framework-core[agent-hooks]"

A agent-hooks-sdk dependência é importada lentamente. A importação agent_framework não carrega o SDK, a menos que você crie um pacote de middleware do Agent Hooks.

Adicionar um interceptor

Um interceptador recebe um agent_hooks.AgentContext (mapeamento de contexto da especificação, não o agent_framework.AgentContext usado pelo middleware do agente) e retorna um veredicto. O interceptador a seguir bloqueia a saída final que contém a palavra secret. O exemplo pressupõe client ser um cliente de chat do Agent Framework já configurado.

from agent_framework import Agent, create_agent_hooks_middleware
from agent_hooks import ALLOW, AgentContext, InterceptionBlocked, Verdict


class SecretEgressGuard:
    def intercept(self, context: AgentContext) -> Verdict:
        if (
            context["interception_point"] == "output"
            and "secret" in str(context["target"]).lower()
        ):
            return Verdict.deny(
                reason="secret_in_output",
                message="The final response contains restricted content.",
            )
        return ALLOW


hooks = create_agent_hooks_middleware(
    {"secret-egress": SecretEgressGuard()},
)

agent = Agent(
    client=client,
    instructions="You are a helpful assistant.",
    middleware=[hooks],
)

try:
    response = await agent.run("Summarize the account details.")
except InterceptionBlocked as exc:
    print(f"Blocked: {exc.result.verdict.reason}")

Passe o pacote como um elemento da lista do middleware agente. Instale exatamente um pacote do Agent Hooks em cada agente.

Pontos de interceptação

O Agent Framework emite automaticamente os pontos de interceptação aplicáveis:

Uma execução que chama uma ferramenta normalmente emite:

agent_startup input → → pre_model_call → → post_model_call → pre_tool_call → → post_tool_call → → post_model_callpre_model_call → → → outputagent_shutdown

Veredictos

O contrato tem três decisões: allow, denye transform. O SDK do Python também fornece auxiliares para avisos e negações liftable.

O nível de execução e o nível do modelo nega o aumento InterceptionBlocked e impede que o resultado protegido atinja o chamador ou o próximo estágio. Em uma costura de ferramenta, uma negação de política impede a ação da ferramenta ou descarta seu resultado e retorna um erro de controle que contém o motivo da política, sem a carga de destino negada, para o modelo. Isso permite que o loop do agente continue. Uma falha de host ou de imposição interrompe a execução.

Aplicar uma transformação

Um caminho de transformação deve começar em $target. Por exemplo, um interceptor pode substituir o conteúdo da resposta final:

from agent_hooks import ALLOW, AgentContext, Decision, Transform, Verdict


class OutputRedactor:
    def intercept(self, context: AgentContext) -> Verdict:
        if context["interception_point"] != "output":
            return ALLOW

        return Verdict(
            decision=Decision.TRANSFORM,
            reason="redacted_output",
            transform=Transform(
                path="$target.content",
                value="[Response removed by policy]",
            ),
        )

As transformações são aplicadas a valores do Agent Framework Content , preservando conteúdo avançado com suporte em vez de reduzir cada valor para texto sem formatação. Um caminho malformado ou uma substituição incompatível falha ao fechar em vez de continuar com o valor original.

Aprovação da ferramenta e transformações de argumento

A aprovação da ferramenta do Agent Framework e a costura de aprovação do Agent Hooks são mecanismos separados. Para uma ferramenta de função com approval_mode="always_require"o Agent Framework cria a solicitação de aprovação humana antes da execução do middleware de função. Uma pre_tool_call transformação pode, portanto, alterar argumentos depois que o usuário aprovou os valores originais.

Streaming e persistência

O Agent Hooks mantém a API de streaming, mas usa semântica de saída em buffer. O Agent Framework monta a resposta completa do modelo, emite post_model_call, monta a resposta final do agente e emite output antes de liberar as atualizações. Se um dos pontos negar a resposta, o chamador não receberá atualizações parciais.

Esse comportamento negocia a latência token por token para a imposição de saída com fail closed. Uma transformação de saída também é refletida nas atualizações eventualmente liberadas para o chamador.

A persistência é fechada pelo ponto de interceptação que abrange a operação de persistência:

• Por padrão, o histórico e outros trabalhos do provedor após a execução esperam pelo output veredicto. Uma saída negada não é mantida e uma transformação de saída é mantida após a transformação.
• Quando você define require_per_service_call_history_persistence=True no Agent construtor ou client.as_agent(...), cada troca de modelo é mantida após o post_model_call veredicto permitir. Uma negação posterior output não reverte esse histórico já permitido.
• Para persistência pós-execução padrão, as tentativas de repetição permanecem por trás da decisão final output . Em vez disso, o modo de chamada por serviço persiste cada resposta de modelo que passa post_model_call.

Sessões e registros de auditoria

Por padrão, cada execução de agente cria uma sessão do Agent Hooks. agent_startup e colchete agent_shutdown da execução e os registros recebem uma ID de sessão com uma sequência de aumento monotonicamente.

Use record_sink para receber cada InterceptionRecordum:

records = []

hooks = create_agent_hooks_middleware(
    {"secret-egress": SecretEgressGuard()},
    record_sink=records.append,
)

Os registros de interceptação capturam a decisão, o motivo, o resumo do interceptor, o modo, a identidade e a sequência sem copiar a carga interceptada no registro de auditoria. O interceptor em si ainda recebe o contexto completo.

Abranger várias execuções com uma sessão

Use create_agent_hooks_middleware_from_emitter() quando o aplicativo possui uma sessão do Agent Hooks de vida mais longa, como uma conversa com um razão de aprovação:

from agent_framework import Agent, create_agent_hooks_middleware_from_emitter
from agent_hooks import AgentContextBuilder, InterceptionEmitter


emitter = InterceptionEmitter().register(SecretEgressGuard())
builder = AgentContextBuilder(
    agent_id="support-agent",
    framework="agent-framework",
    session_id="conversation-42",
)

hooks = create_agent_hooks_middleware_from_emitter(emitter, builder)
agent = Agent(client=client, middleware=[hooks])

await emitter.emit(builder.agent_startup(tools_registered=[]))
await agent.run("First turn")
await agent.run("Second turn")
await emitter.emit(builder.agent_shutdown(reason="completed"))

Nesse formulário, o aplicativo configura o emissor e possui a inicialização, o desligamento e a limpeza de erros. O middleware emite os pontos por execução de input até output.

Configurar a imposição

create_agent_hooks_middleware() aceita os seguintes controles:

A composição padrão é sequencial first_deny com aprovação configurada para interromper a dobra. Portanto, a ordem do interceptor é importante: coloque controles que sempre devem ser executados antes dos controles que podem solicitar aprovação. Consulte a lista de verificação de produção do Agent Hooks antes de selecionar outro perfil de composição.

Implantar com o modo somente avaliação

Use evaluate_only para medir o comportamento da política antes da imposição:

hooks = create_agent_hooks_middleware(
    {"secret-egress": SecretEgressGuard()},
    mode="evaluate_only",
    record_sink=records.append,
)

Nesse modo, os interceptores são executados e os registros incluem seus veredictos, mas nenhuma ação é bloqueada ou transformada. Não descreva uma implantação evaluate_only como governança imposta.

Regras de composição

Coloque o pacote primeiro na lista de middleware do agente para que ele forme o limite de imposição mais externo:

agent = Agent(
    client=client,
    middleware=[
        create_agent_hooks_middleware([SecretEgressGuard()]),
        application_middleware,
    ],
)

Siga estas regras:

• Instale exatamente um pacote do Agent Hooks por agente. Os pacotes empilhados são rejeitados.
• Mantenha o pacote intacto. Seu middleware de agente, chat e função não pode ser instalado separadamente.
• Instale o pacote, Agentnão diretamente em um cliente de chat ou por meio de um provedor de contexto.
• Middleware colocado antes que o pacote esteja fora do limite de imposição. Trate a posição externa como confiança externa.
• Dê a cada agente aninhado seu próprio pacote quando seu modelo interno e atividade de ferramentas também precisarem de interceptação.

Limitações atuais

• Python somente: os Ganchos do Agente ainda não foram implementados nos SDKs de .NET ou Go.
• API experimental: As assinaturas de fábrica e o comportamento podem ser alterados antes da disponibilidade geral.
• Streaming em buffer: As atualizações não são lançadas token por token porque a saída deve ser concluída antes de um veredito fechado por fail-closed.
• Ferramentas hospedadas: As ferramentas executadas por um provedor de modelos não passam pela costura de invocação de função do Agent Framework. Suas chamadas e saídas são exibidas post_model_call, mas pre_tool_callpost_tool_call não podem bloquear a execução do lado do servidor do provedor.
• Limite cooperativo: O Agent Hooks não protege interceptadores de área restrita ou contra um host hostil. Caminhos de código que ignoram o pipeline do agente protegido não são cobertos.
• A disponibilidade do interceptor afeta a disponibilidade do agente: No modo de imposição, uma falha ou tempo limite do interceptor bloqueia a ação protegida por design.

Para obter distribuição de produção, motivos de falha e diretrizes de alerta, consulte o runbook de operações do Agent Hooks.

O Agent Hooks ainda não está disponível para o Go. Use o middleware do agente, a aprovação da ferramenta e a segurança do agente para adicionar controles de runtime aos agentes do Go.