Ganchos de agente

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

O Agent Hooks é experimental em Python. A fábrica emite um ExperimentalWarning quando é usada pela primeira vez, e a sua API pode mudar antes da disponibilidade geral.

Quando usar Ganchos de Agente

Use Ganchos de Agente quando os controlos desenvolvidos de forma independente necessitam de um contrato partilhado e executável entre a entrada do agente, chamadas de modelo, chamadas de ferramentas e saída final.

O que o Agent Framework aplica

Quando adiciona Ganchos de Agente a um agente, o Quadro de Agentes aplica uma fronteira de aplicação coordenada entre execuções de agentes, chamadas de modelo e chamadas de ferramentas. O tempo de execução oferece as seguintes garantias:

• Falha encerrada: Uma negação bloqueia a ação defensiva. Contextos inválidos, veredictos inválidos, falhas de interceptores e falhas de aplicação não contornam silenciosamente os controlos.
• Escrita por transformação: Uma transformação altera as mensagens nativas, argumentos da ferramenta, resultados da ferramenta ou resposta final que a execução realmente utiliza. Se uma transformação não puder ser aplicada, a execução falha fechada.
• Streaming com buffer: Nenhuma atualização de resposta chega ao chamador até que a resposta completa do modelo e a saída final ultrapassem os seus pontos de interceção.
• Persistência limitada ao veredicto: A persistência espera pelo veredito que a cobre. A persistência pós-execução padrão espera por output; a persistência do histórico de chamadas de serviço espera para cada post_model_call.
• Instalação completa do pacote: O agente, o chat e as partes funcionais são instalados como uma só unidade, por isso não se pode configurar acidentalmente um limite de fiscalização incompleto.

O contrato é cooperativo e não uma fronteira de isolamento de processo. Os interceptores correm no processo anfitrião e recebem o conteúdo necessário para tomar decisões. Regista apenas interceptores em quem confies.

Ganchos de Agente de Instalação

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

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

Caso utilize uv:

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

A agent-hooks-sdk dependência é importada de forma preguiçosa. Importar agent_framework não carrega o SDK a menos que crie um bundle de middleware Agent Hooks.

Adicionar um interceptor

Um interceptor recebe um agent_hooks.AgentContext (o mapeamento de contexto da especificação, não o agent_framework.AgentContext middleware usado pelo agente) e devolve um veredito. O interceptor seguinte bloqueia a saída final contendo a palavra secret. O exemplo assume client que é um cliente de chat 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 Agent Hooks em cada agente.

Pontos de interceção

O Agent Framework emite automaticamente os pontos de interceçã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 → pre_model_call → post_model_call → output → agent_shutdown

Vereditos

O contrato tem três decisões: allow, deny, e transform. O SDK Python também fornece ajudantes para avisos e recusas levantáveis.

As recusas ao nível de execução e ao nível do modelo aumentam InterceptionBlocked e impedem que o resultado guardado chegue ao chamador ou ao próximo estágio. Numa costura de ferramenta, uma recusa de política impede a ação da ferramenta ou descarta o seu resultado e devolve um erro de controlo contendo a razão da política, sem a carga útil alvo negada, ao modelo. Isto permite que o ciclo de agentes continue. Uma falha no host ou na aplicação da aplicação interrompe a corrida.

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 aos valores do Agent Framework Content , preservando o conteúdo rico suportado em vez de reduzir todos os valores a texto simples. Um caminho malformado ou substituição incompatível falha ao fechar em vez de continuar com o valor original.

Aprovação de ferramentas e transformações de argumentos

A aprovação da ferramenta Agent Framework e a junção de aprovação Agent Hooks são mecanismos separados. Para uma ferramenta de funções com approval_mode="always_require", o Agent Framework cria o pedido de aprovação humana antes de o middleware de funções ser executado. Uma pre_tool_call transformação pode, portanto, alterar argumentos depois de o utilizador aprovar os valores originais.

Transmissão e persistência

O Agent Hooks mantém a API de streaming mas utiliza 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 lançar quaisquer atualizações. Se qualquer um dos pontos negar a resposta, o chamador não recebe atualizações parciais.

Este comportamento troca a latência token a token pela aplicação de saída falha-fechada. Uma transformação de saída também se reflete nas atualizações eventualmente lançadas ao chamador.

A persistência é limitada pelo ponto de interceção que cobre a operação de persistência:

• Por defeito, o histórico e outros trabalhos de prestadores após a corrida aguardam pelo output veredicto. Uma saída negada não é persistida, e uma transformação de saída é mantida após a transformação.
• Quando se define require_per_service_call_history_persistence=True no Agent construtor ou client.as_agent(...), cada troca de modelos é mantida após o seu post_model_call veredicto o permitir. Uma recusa posterior output não reverte o que já permitiu a história.
• Para persistência padrão após a corrida, as tentativas de retentativa permanecem atrás da decisão final output . O modo por chamada de serviço persiste, em vez disso, cada resposta do modelo que passa post_model_callpor .

Sessões e registos de auditoria

Por defeito, cada execução de agente cria uma sessão de Ganchos de Agente. agent_startup e agent_shutdown colocam a execução entre parênteses, e os registos recebem um ID de sessão com uma sequência monotonamente crescente.

Usar record_sink para receber cada InterceptionRecordum :

records = []

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

Os registos de interceção capturam a decisão, razão, resumo do interceptor, modo, identidade e sequência sem copiar a carga útil interceptada para o registo de auditoria. O próprio interceptor ainda recebe todo o contexto.

Abrange várias corridas numa só sessão

Use create_agent_hooks_middleware_from_emitter() quando a aplicação possui uma sessão de Agent Hooks de duração mais longa, como uma conversa com um registo 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"))

Nesta forma, a aplicação configura o emissor e é responsável pelo arranque, desligamento e limpeza de erros. O middleware emite os pontos por corrida de input através outputde .

Configurar a aplicação

create_agent_hooks_middleware() Aceita os seguintes controlos:

A composição padrão é sequencial first_deny , com aprovação configurada para parar a dobra. A ordem do interceptor importa, portanto: colocar os controlos que devem sempre funcionar antes dos controlos que podem pedir aprovação. Consulte a lista de verificação de produção do Agent Hooks antes de selecionar outro perfil de composição.

Implemente o modo apenas de avaliação

Utilização evaluate_only para medir o comportamento das políticas antes da aplicação:

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

Neste modo, os interceptores correm e os registos incluem os seus veredictos, mas nenhuma ação é bloqueada ou transformada. Não descreva uma evaluate_only implantação como governação imposta.

Regras de composição

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

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

Siga estas regras:

• Instale exatamente um pacote Agent Hooks por agente. Os pacotes empilhados são rejeitados.
• Mantém o embrulho intacto. O seu agente, chat e middleware de funções não podem ser instalados separadamente.
• Instala o bundle, Agentnão diretamente num cliente de chat ou através de um fornecedor de contexto.
• O middleware colocado antes do pacote está fora do limite de fiscalização. Trate a posição exterior como confiança externa.
• Dê a cada agente aninhado o seu próprio bundle quando a sua atividade interna de modelo e ferramenta também precisa de interceção.

Limitações atuais

• Apenas Python: O Agent Hooks ainda não está implementado nos SDKs .NET ou Go.
• API Experimental: As assinaturas e comportamentos da fábrica podem mudar antes da disponibilidade geral.
• Streaming com buffer: As atualizações não são lançadas token a token porque a saída tem de estar completa antes de um veredito de falha fechada.
• Ferramentas alojadas: Ferramentas executadas por um fornecedor de modelos não passam pela costura de invocação de funções do Agent Framework. As suas chamadas e saídas são apresentadas em post_model_call, mas pre_tool_callpost_tool_call não podem bloquear a execução do servidor do fornecedor.
• Fronteira cooperativa: O Agente Hooks não faz sandbox para interceptores nem protege contra um hospedeiro hostil. Caminhos de código que contornam o pipeline de agentes protegidos não são cobertos.
• A disponibilidade de interceptores afeta a disponibilidade dos agentes: No modo de imposição, uma falha ou timeout do interceptor bloqueia a ação guardada por design.

Para lançamento em produção, razões de falha e orientações de alerta, consulte o manual de operações do Agent Hooks.

O Agente Hooks ainda não está disponível para o Go. Use middleware de agentes, aprovação de ferramentas e segurança de agentes para adicionar controlos de execução aos agentes Go.