Aracı kancaları

Aracı Kancaları, bir aracının yürütülmesinde iyi tanımlanmış noktalarda idare ve çalışma zamanı denetimlerini uygulamaya yönelik birinci sınıf bir Aracı Çerçevesi özelliğidir. Çerçeveden bağımsız AGENT-HOOKS-0.1 sözleşmesini uygular, bu nedenle ilke altyapıları, onay ağ geçitleri, bütçe korumaları, içerik filtreleri ve çıkış denetimleri ortak bir denetim yüzeyini hedefleyebilir.

Önemli

Ajan Hooks bir denetim düzlemidir, telemetri düzlemi değildir. Her interceptor bir karar döndürür. enforce modunda çerçeve bu karara göre işlem yapar; evaluate_only modunda ise yürütmeyi değiştirmeden kararı kaydeder. Pasif izleme, ölçümler ve günlükler için gözlemlenebilirliği kullanın.

Agent Hooks henüz .NET için kullanıma sunulmadı. .NET aracılarına çalışma zamanı denetimleri eklemek için aracı ara yazılımını, araç onayını ve aracı güvenliğini kullanın.

Ajan Hooks Python'da deneyseldir. Fabrika ilk kullanıldığında bir ExperimentalWarning yayar ve API'si genel kullanılabilirlik öncesinde değişebilir.

Agent Hooks ne zaman kullanılır?

Bağımsız olarak geliştirilen kontrollerin ajan girdisi, model çağrıları, araç çağrıları ve nihai çıktı genelinde paylaşılan ve uygulanabilir tek bir sözleşmeye ihtiyaç duyduğu durumlarda Agent Hooks kullanın.

Capability	Şunun için kullanın
Ajan Kancaları	Ajan yaşam döngüsü boyunca standartlaştırılmış politika kararları, dönüşümler, onaylar, bütçeler ve egres kontrolleri.
Aracı yazılım	Agent Hooks sözleşmesine veya onun temel çalışma zamanı güvencelerine ihtiyaç duymayan, uygulamaya özgü kesişen kaygı davranışı.
FIDES ile Ajan Güvenliği	Güvenilmeyen veya gizli içerik için belirlenimci bilgi akışı etiketleri ve ilkeleri.
Araç onayı	Her bir işlev-araç çağrısının insan tarafından onaylanması.
Gözlemlenebilirlik	Yürütmeyi denetlemeyen pasif izlemeler, ölçümler ve günlükler.

Agent Framework'ün zorunlu kıldığı şeyler

Bir ajana Agent Hooks eklediğinizde, Agent Framework ajan çalıştırmaları, model çağrıları ve araç çağrıları genelinde eşgüdümlü bir zorunlu denetim sınırı uygular. Çalışma zamanı aşağıdaki garantileri sağlar:

• Başarısız kapatma: Reddetme, korunan eylemi engeller. Geçersiz bağlamlar, geçersiz kararlar, araya girici başarısızlıkları ve uygulama başarısızlıkları denetimleri sessizce atlatmaz.
• Dönüşüm geri yazımı: Bir dönüşüm, yürütme tarafından gerçekten kullanılan yerel iletileri, araç argümanlarını, araç sonuçlarını veya son yanıtı değiştirir. Bir dönüşüm uygulanamazsa, çalışma kapalı durumda başarısız olur.
• Arabellekli akış: Tam model yanıtı ve nihai çıktı, ilgili yakalama noktalarını geçene kadar hiçbir yanıt güncelleştirmesi çağıran tarafa ulaşmaz.
• Karara bağlı kalıcılık: Kalıcılık, kendisiyle ilgili kararı bekler. Standart çalıştırma sonrası kalıcılık, output öğesini bekler; hizmet çağrısı başına geçmiş kalıcılığı ise her post_model_call için bekler.
• Paket yüklemesini tamamlayın: Aracı, sohbet ve işlev bölümleri tek bir birim olarak yüklenir, bu nedenle tamamlanmamış bir zorlama sınırı yanlışlıkla yapılandırılamaz.

Sözleşme, işlem yalıtım sınırı yerine işbirliğine dayalıdır. Önleyiciler ana bilgisayar işleminde çalışırlar ve karar vermek için gereken içeriği alırlar. Yalnızca güvendiğiniz önleyicileri kaydedin.

Ajan Kancalarını Yükle

Agent Hooks SDK'sını doğrudan bağımlılık olarak yükleyin:

pip install agent-hooks-sdk

Eğer siz uv kullanıyorsanız:

uv add agent-hooks-sdk

Bağımlılık agent-hooks-sdk yavaş içeri aktarılır. agent_framework öğesini içe aktarmak, bir Agent Hooks ara katman paketi oluşturmadığınız sürece SDK’yı yüklemez.

Uyarı

agent-framework-core, agent-hooks ek özelliğini içermez. agent-hooks-sdk öğesini, Agent Hooks ara katman paketi oluşturmadan önce ayrı olarak yükleyin.

Kesici ekle

Bir yakalama işleyicisi bir agent_hooks.AgentContext alır (aracı ara katmanı tarafından kullanılan agent_framework.AgentContext değil, belirtimin bağlam eşlemesi) ve bir karar döndürür. Aşağıdaki önleyici, secret sözcüğünü içeren son çıktıyı engeller. Örnekte zaten yapılandırılmış bir Agent Framework sohbet istemcisi olduğu varsayılır client .

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}")

Paketi aracı middleware listesinin bir öğesi olarak geçirin. Her ajan üzerine tam olarak bir Agent Hooks paketi yükleyin.

Yakalama noktaları

Agent Framework, uygulanabilir müdahale noktalarını otomatik olarak oluşturur:

Yakalama noktası	Yayıldığında	Hedefi dönüştürme
agent_startup	Agent Hooks oturumunda ilk girdiden önce	Dönüştürülemez
input	Harici bir istek aracıya ulaştığında	Giriş içeriği ve rolü
pre_model_call	Her model isteğinden önce	Modele gönderilen iletiler
post_model_call	Tüm model yanıtlarının ardından	Yanıt içeriği, çerçevenin yürüttüğü araç çağrıları ve bitiş nedeni
pre_tool_call	Çerçevede yürütülen her araç çağırmadan önce	Araç parametreleri
post_tool_call	Bir araç başarılı veya başarısız olduktan sonra	Araç çıktısı
output	Son yanıt arayana ulaşmadan önce	Son yanıt içeriği
agent_shutdown	Agent Hooks oturumu tamamlandığında, başarısız olduğunda veya iptal edildiğinde	Dönüştürülemez

agent_startup.tools_registered run-start aracının anlık görüntüsüdür. Her pre_model_call yükü, isteğe bağlı tools alanında o model çağrısı için geçerli olan araçları içerir. Buna, çalışma sırasında bağlam sağlayıcıları, bağlı MCP sunucuları veya aşamalı gösterim tarafından eklenen araçlar da dahildir. Çağrıda araç olmadığında veya araç kümesi yansıtılamadığında bu alan dahil edilmez.

Bir aracı çağıran bir çalışma genellikle şunu üretir:

agent_startup → pre_model_call → post_model_call → pre_tool_call → post_tool_call → output → pre_model_call → post_model_call → input → agent_shutdown

Hükümler

Sözleşmenin üç kararı vardır: allow, denyve transform. Python SDK ayrıca uyarılar ve kaldırılabilir engellemeler için yardımcı işlevler sunar.

Result	Python API'si	Davranış
İzin ver	ALLOW veya Verdict(decision=Decision.ALLOW)	Hedefi değiştirmeden devam edin.
Uyarıyla izin ver	Verdict.warn(...)	Devam edin ve uyarıyı engelleme kaydına ekleyin.
Reddet	Verdict.deny(...)	Korumalı eylemi engelleyin.
Bekleyen onayı reddet	Verdict.escalate(...)	Yapılandırılan onay çözümleyicisi bir izin kararı döndürmediği sürece engelle.
Dönüşüm	Verdict(decision=Decision.TRANSFORM, transform=Transform(...))	altında $targetbir değeri yeniden yazın ve yeniden yazılan değerle devam edin.

Çalışma düzeyi ve model düzeyi reddetmeleri, InterceptionBlocked oluşturur ve korunan sonucun çağırana veya sonraki aşamaya ulaşmasını engeller. Bir araç birleşim noktasında, bir ilke reddi araç eylemini engeller veya sonucunu yok sayar ve reddedilen hedef yükü olmaksızın, ilke nedenini içeren bir denetim hatasını modele döndürür. Bu durum, ajan döngüsünün devam etmesini sağlar. Bir ana bilgisayar veya uygulama hatası çalıştırma işlemini durdurur.

İşlev ara yazılımından çalıştırmayı durdurma

MiddlewareFailure öğesini agent_framework öğesinden içeri aktar. İşlev ara yazılımı normalde sıradan bir özel durumu bir araç hatası sonucuna dönüştürür ve aracı döngüsünün devam etmesine olanak tanır. İşlev ara katmanı güvenli bir şekilde devam edemiyorsa, MiddlewareFailure özel durumunu temelindeki özel durumdan türeterek fırlatın. Çalışma zamanı, çalıştırmayı durdurur ve bunu bir araç sonucuna dönüştürmek yerine başarısızlığı çağırana iletir.

Ara katmanda MiddlewareFailure yakalamayın. Bunun yakalanması, döngünün devam etmesini sağlar ve fail-closed davranışını fail-open davranışına dönüştürür. Agent Hooks, işlev ara yazılımı yaptırım katmanı başarısız olduğunda bu sinyali dahili olarak kullanır. Özel, hata durumunda kapalı kalan ara yazılımı bir sıra halinde iletin; örneğin, middleware=[policy_middleware].

Eşzamanlı araç çağrıları için çalışma zamanı, hatayı yaymadan önce uçuş içi eşdüzey çağrıları iptal eder. İptal iş birliğine dayalıdır; bu nedenle, bir worker iş parçacığında zaten çalışmakta olan eşzamanlı bir araç yan etkilerini tamamlayabilir, ancak sonucu göz ardı edilir.

Bir dönüşüm uygula

Bir dönüşüm yolu adresinden $targetbaşlamalıdır. Örneğin, bir önleyici nihai yanıt içeriğini değiştirebilir:

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]",
            ),
        )

Dönüştürmeler, Her değeri düz metne düşürmek yerine desteklenen zengin içeriği koruyarak Agent Framework Content değerlerine uygulanır. Hatalı biçimlendirilmiş bir yol veya uyumsuz bir değiştirme, özgün değerle devam etmek yerine kapalı durumda başarısız olur.

Araç onayı ve argüman dönüştürmeleri

Agent Framework araç onayı ile Agent Hooks onay mekanizması, birbirinden ayrı mekanizmalardır. ile approval_mode="always_require"bir işlev aracı için Agent Framework, işlev ara yazılımı çalışmadan önce insan onay isteği oluşturur. Bir pre_tool_call dönüşüm, bu nedenle, kullanıcı özgün değerleri onayladıktan sonra argümanları değiştirebilir.

Warning

pre_tool_call kullanan araçlarda approval_mode="always_require" konumundaki bağımsız değişkenleri dönüştürmeyin. Çerçeve onay isteğinin dönüştürülen değerleri içermesi için post_model_call konumundaki araç çağrısını dönüştürün veya Verdict.escalate(...) konumunda resolver döndürün ve onayı Agent Hooks pre_tool_call aracılığıyla çözümleyin.

Akış ve kalıcılık

Agent Hooks, akış API’sini korur ancak arabelleğe alınan çıktı semantiğini kullanır. Agent Framework, tüm model yanıtını bir araya getirir, post_model_call yayar, nihai aracı yanıtını bir araya getirir ve herhangi bir güncelleştirme yayımlamadan önce output yayar. İki noktadan biri yanıtı reddederse, çağıran taraf hiçbir kısmi güncelleştirme almaz.

Bu davranış, fail-closed çıktı zorlamasını sağlamak için belirteç bazında gecikmeden ödün verir. Çıkış dönüşümü, nihayetinde çağırana iletilen güncellemelere de yansır.

Kalıcılık, kalıcılık işlemini kapsayan kesme noktası tarafından denetlenir:

• Varsayılan olarak, geçmiş ve diğer çalıştırma sonrası sağlayıcı görevleri output kararını bekler. Reddedilmiş bir çıkış kalıcı olarak saklanmaz ve bir çıkış dönüşümü, dönüşümden sonra kalıcı olarak saklanır.
• Agent oluşturucusunda veya require_per_service_call_history_persistence=True üzerinde client.as_agent(...) ayarını yaptığınızda, her model değişimi, post_model_call kararı buna izin verdikten sonra kalıcı olarak kaydedilir. Sonraki output bir reddetme, önceden izin verilen geçmişe geri dönmez.
• Varsayılan çalıştırma sonrası kalıcılığı için yeniden deneme girişimleri son output kararın arkasında kalır. Hizmet başına çağrı modu bunun yerine geçen her model yanıtlarını kalıcı hale getirir post_model_call.

Önemli

Model içeriğinin dayanıklı hale gelmemesi gerekiyorsa, bu ilkeyi post_model_call zamanında require_per_service_call_history_persistence=Trueuygulayın. Yalnızca çıktı yönlü çıkış ilkesi, çağırana ulaşanı korur; ancak zaten izin verilmiş ve post_model_call konumunda kalıcı olarak saklanmış model etkileşimlerini geriye dönük olarak kaldırmaz.

Oturumlar ve denetim kayıtları

Varsayılan olarak, her ajan çalıştırma işlemi bir Agent Hooks oturumu oluşturur. agent_startup ve agent_shutdown, çalıştırma işleminin sınırlarını belirler ve kayıtlara tek bir oturum kimliği ile monotonik olarak artan bir sıra numarası atanır.

Her record_sink öğesini almak için InterceptionRecord kullanın:

records = []

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

Müdahale kayıtları, müdahale edilen veri yükünü denetim kaydına kopyalamadan karar, neden, müdahale edici özeti, mod, kimlik ve sıra bilgisini kaydeder. Yakalayıcının kendisi yine de tam bağlamı almaya devam eder.

Birden çok çalıştırmayı tek bir oturumla kapsayın

Uygulama, tek bir onay kaydıyla yürütülen bir konuşma gibi daha uzun ömürlü bir Agent Hooks oturumuna sahipse create_agent_hooks_middleware_from_emitter() kullanın:

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"))

Bu formda uygulama, vericiyi yapılandırarak başlatma, kapatma ve hata temizlemenin sahibi olur. Ara yazılım, output ile input arasındaki çalıştırma başına noktaları yayar.

Zorlamayı yapılandırma

create_agent_hooks_middleware() aşağıdaki denetimleri kabul eder:

Parametre	Purpose
interceptors	Bir önleyici dizisi veya ad-önleyici eşlemesi. En az bir tane gereklidir.
resolver	Onay kanalı aracılığıyla kaldırılabilir retleri çözümler. Çözümleyici olmadan reddetme etkin kalır.
mode	"enforce" kararları uygular. "evaluate_only" ne olacağını kaydeder, ancak her eyleme izin verir.
composition	Birden çok kesme noktası kararının nasıl birleştirildiği seçer.
identity_provider	İçeriğe bağlı bağlam kimlikleri oluşturur. Varsayılan değer: "jcs-sha256".
timeout	Beklenebilen aramalar için kesme noktası başına ve çözümleyici zaman aşımı. Varsayılan değer beş saniyedir. Olay döngüsünü engelleyen eşzamanlı bir ara yazılım veya çözümleyici, bu zaman aşımı tarafından kesintiye uğratılamaz.
record_sink	Her veri yükü içermeyen yakalama kaydını alır.

Varsayılan bileşim, katlamayı durduracak şekilde yapılandırılmış onay ile sıralı first_deny şeklindedir. Bu nedenle önleyicilerin sırası önemlidir: her zaman çalışması gereken denetimleri, onay isteyebilen denetimlerden önce yerleştirin. Başka bir oluşturma profili seçmeden önce Agent Hooks üretim denetim listesine bakın.

Yalnızca değerlendirme moduyla kullanıma sunma

Zorlamadan önce ilke davranışını ölçmek için kullanın evaluate_only :

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

Bu modda, yakalayıcılar çalışır ve kayıtlar verdikleri kararları içerir, ancak hiçbir işlem engellenmez veya dönüştürülmez. evaluate_only dağıtımı zorunlu yönetişim olarak tanımlamayın.

Oluşturma kuralları

Bundle'ı, en dıştaki zorlama sınırını oluşturacak şekilde ajanın ara yazılım listesinde ilk sıraya yerleştirin:

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

Şu kuralları izleyin:

• Aracı başına tam olarak bir Aracı Kancası paketi yükleyin. Üst üste istiflenmiş demetler kabul edilmez.
• Paketi olduğu gibi tutun. Aracısı, sohbeti ve işlev ara katmanı ayrı ayrı yüklenemez.
• Paketi, doğrudan bir sohbet istemcisine veya bir bağlam sağlayıcısı aracılığıyla değil, Agent üzerine yükleyin.
• Paketin önüne yerleştirilen ara yazılım, zorunlu kılma sınırının dışındadır. Dış konumu dış güven olarak değerlendirin.
• Dahili modeli ve araç kullanımı da izlenmesi gerektiğinde, her iç içe geçmiş aracıya kendi ayrı paketini verin.

Mevcut sınırlamalar

• Yalnızca Python: Aracı Kancaları henüz .NET veya Go SDK'larında uygulanmadı.
• Deneysel API: Fabrika imzaları ve davranışı genel kullanılabilirlik öncesinde değişebilir.
• Arabellekli akış: Çıkışın fail-closed kararı verilmeden önce tamamlanması gerektiğinden, güncelleştirmeler tek tek belirteçler halinde iletilmez.
• Barındırılan araçlar: Model sağlayıcısı tarafından yürütülen araçlar Agent Framework'ün işlev çağırma özelliğinden geçmez. Çağrıları ve çıktıları post_model_call içinde görünür, ancak post_tool_call ve pre_tool_call sağlayıcının sunucu tarafındaki yürütmesini engelleyemez.
• İş birliği sınırı: Agent Hooks, interceptor’ları korumalı bir alanda yalıtmaz ve kötü niyetli bir ana makineye karşı koruma sağlamaz. Korumalı ajan işlem hattını atlayan kod yolları kapsanmamaktadır.
• Kesme noktası kullanılabilirliği aracı kullanılabilirliğini etkiler: Zorlama modunda bir kesme noktası hatası veya zaman aşımı, korunan eylemi tasarım gereği engeller.

Üretime alma, hata nedenleri ve uyarı yönergeleri için Agent Hooks operasyon runbook’una bakın.

Agent Hooks, Go için henüz kullanıma sunulmamıştır. Go aracılarına çalışma zamanı denetimleri eklemek için aracı ara yazılımını, araç onayını ve aracı güvenliğini kullanın.

Sonraki Adımlar

Aracı işlem hattını anlama

İlgili içerik

• Aracı yazılım
• Aracı güvenliği
• Araç onayı
• FIDES ile Ajan Güvenliği
• Gözlemlenebilirlik
• AGENT-HOOKS-0.1 belirtimi