خطافات العملاء

Agent Hooks هي قدرة إطار عمل عامل من الدرجة الأولى لتطبيق عناصر التحكم في الحوكمة ووقت التشغيل في نقاط محددة جيدا في تنفيذ العامل. ينفذ عقد AGENT-HOOKS-0.1 المحايد لإطار العمل، بحيث يمكن لمحركات النهج وبوابات الموافقة وحراس الموازنة وعوامل تصفية المحتوى وعناصر التحكم في الخروج استهداف سطح تحكم واحد مشترك.

Important

الوكيل Hooks هو مستوى تحكم، وليس مستوى بيانات تتبع الاستخدام. كل معترض يرجع حكم. وفي enforce الوضع، يعمل الإطار على هذا الحكم؛ وفي evaluate_only الوضع، يسجل الحكم دون تغيير التنفيذ. استخدم إمكانية المراقبة للتتبع السلبي والمقاييس والسجلات.

عامل Hooks غير متوفر حتى الآن .NET. استخدم البرنامج الوسيط للعاملوالموافقة على الأدواتوأمان العامل لإضافة عناصر تحكم وقت التشغيل إلى عوامل .NET.

عامل Hooks تجريبي في Python. يصدر ExperimentalWarning المصنع عند استخدامه لأول مرة، ويمكن تغيير واجهة برمجة التطبيقات الخاصة به قبل التوفر العام.

متى تستخدم الخطافات الوكيلة

استخدم Agent Hooks عندما تحتاج عناصر التحكم المطورة بشكل مستقل إلى عقد مشترك وقابل للتنفيذ عبر إدخال العامل ومكالمات النموذج واستدعاءات الأدوات والإخراج النهائي.

Capability	استخدمه ل
خطافات الوكيل	قرارات النهج الموحدة والتحويلات والموافقات والميزانيات وعناصر التحكم في الخروج عبر دورة حياة العامل.
البرنامج الوسيط للعامل	سلوك شامل خاص بالتطبيق لا يحتاج إلى عقد Agent Hooks أو ضمانات وقت التشغيل الأساسية الخاصة به.
أمان العامل مع FIDES	تسميات ونهج تدفق المعلومات المحددة للمحتوى غير الموثوق به أو السري.
الموافقة على الأداة	تأكيد بشري لمكالمات أداة الوظائف الفردية.
إمكانية المراقبة	التتبعات السلبية والمقاييس والسجلات التي لا تتحكم في التنفيذ.

ما يفرضه إطار عمل العامل

عند إضافة Agent Hooks إلى عامل، يطبق إطار عمل العامل حد فرض منسق عبر عمليات تشغيل العامل ومكالمات النموذج ومكالمات الأدوات. يوفر وقت التشغيل الضمانات التالية:

• فشل الإغلاق: يمنع الرفض الإجراء المحمي. لا تتجاوز السياقات غير الصالحة والأحكام غير الصالحة وفشل المعترض وفشل التنفيذ عناصر التحكم بصمت.
• تحويل إعادة الكتابة: يغير التحويل الرسائل الأصلية أو وسيطات الأدوات أو نتائج الأدوات أو الاستجابة النهائية التي يستخدمها التنفيذ فعليا. إذا تعذر تطبيق تحويل، يفشل التشغيل في الإغلاق.
• الدفق المخزن مؤقتا: لا يصل أي تحديث استجابة إلى المتصل حتى تمر استجابة النموذج الكاملة والإخراج النهائي نقاط الاعتراض الخاصة بهم.
• استمرارية الحكم: والمثابرة تنتظر الحكم الذي يغطيها. ينتظر استمرار التشغيل القياسي بعد outputالتشغيل ؛ وينتظر استمرار كل محفوظات استدعاء لكل خدمة لكل post_model_call.
• إكمال تثبيت المجموعة: يتم تثبيت أجزاء العامل والدردشة والدالة كوحدة واحدة، لذلك لا يمكن تكوين حد إنفاذ غير كامل عن طريق الخطأ.

العقد تعاوني وليس حدود عزل عملية. تعمل المعترضات في عملية المضيف وتتلقى المحتوى اللازم لاتخاذ القرارات. تسجيل المعترضات التي تثق بها فقط.

تثبيت خطافات الوكيل

تثبيت الإضافية الاختيارية agent-hooks للحزمة الأساسية:

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

إذا كنت تستخدم uv:

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

التبعية agent-hooks-sdk مستوردة كسولة. لا يؤدي agent_framework الاستيراد إلى تحميل SDK إلا إذا قمت بإنشاء حزمة برامج وسيطة ل Agent Hooks.

Note

agent-hooks لا يتم تضمين الإضافات عمدا في agent-framework-core[all]. قم بتثبيته بشكل صريح عندما تريد تمكين سطح التحكم التجريبي هذا.

إضافة اعتراض

يتلقى agent_hooks.AgentContext المعترض (تعيين سياق المواصفات، وليس agent_framework.AgentContext المستخدم من قبل البرنامج الوسيط للعامل) ويعيد حكما. يمنع المعترض التالي الإخراج النهائي الذي يحتوي على الكلمة secret. يفترض 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}")

مرر الحزمة كعنصر واحد في قائمة العامل middleware . تثبيت حزمة Agent Hooks واحدة بالضبط على كل عامل.

نقاط الاعتراض

يصدر إطار عمل العامل نقاط الاعتراض القابلة للتطبيق تلقائيا:

نقطة اعتراض	عندما يتم إصداره	تحويل الهدف
agent_startup	قبل الإدخال الأول في جلسة عمل Agent Hooks	غير قابل للتحويل
input	عندما يدخل طلب خارجي العامل	إدخال المحتوى والدور
pre_model_call	قبل كل طلب نموذج	الرسائل المرسلة إلى النموذج
post_model_call	بعد كل استجابة نموذج كاملة	محتوى الاستجابة واستدعاءات الأدوات المنفذة في إطار العمل وسبب الانتهاء
pre_tool_call	قبل استدعاء كل أداة منفذة في إطار العمل	مُعاملات الأداة
post_tool_call	بعد نجاح أداة أو فشلها	نتيجة الأداة
output	قبل أن تصل الاستجابة النهائية إلى المتصل	محتوى الاستجابة النهائية
agent_shutdown	عند اكتمال جلسة عمل Agent Hooks أو فشلها أو إلغاؤها	غير قابل للتحويل

عادة ما يصدر تشغيل يستدعي أداة ما:

agent_startup input pre_model_call → → pre_tool_callpost_model_call → → → → → → post_model_calloutput → pre_model_call → → post_tool_call → →agent_shutdown

الأحكام

يحتوي العقد على ثلاثة قرارات: allowو denyو.transform يوفر Python SDK أيضا مساعدين للتحذيرات والرفضات القابلة للرفع.

النتيجة	واجهة برمجة تطبيقات Python	السلوك
السماح	ALLOW او Verdict(decision=Decision.ALLOW)	تابع مع الهدف دون تغيير.
السماح مع التحذير	Verdict.warn(...)	تابع وقم بتضمين التحذير في سجل الاعتراض.
أنكر	Verdict.deny(...)	حظر الإجراء المحمي.
رفض الموافقة المعلقة	Verdict.escalate(...)	حظر ما لم يقم محلل الموافقة المكون بإرجاع حكم تصريح.
التحويل	Verdict(decision=Decision.TRANSFORM, transform=Transform(...))	أعد كتابة قيمة ضمن $target، ثم تابع مع القيمة المعاد كتابتها.

يؤدي رفض مستوى التشغيل ومستوى النموذج إلى رفع InterceptionBlocked النتيجة المحمية ومنعها من الوصول إلى المتصل أو المرحلة التالية. في التماس أداة، يمنع رفض النهج إجراء الأداة أو يتجاهل نتيجته ويعيد خطأ تحكم يحتوي على سبب النهج، دون حمولة الهدف المرفوضة، إلى النموذج. يسمح هذا لحلقة العامل بالمتابعة. يؤدي فشل المضيف أو التنفيذ إلى إيقاف التشغيل.

تطبيق تحويل

يجب أن يبدأ مسار التحويل في $target. على سبيل المثال، يمكن أن يحل المعترض محل محتوى الاستجابة النهائية:

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

يتم تطبيق التحويلات على قيم إطار عمل Content العامل، مع الحفاظ على المحتوى الغني المدعوم بدلا من تقليل كل قيمة إلى نص عادي. فشل إغلاق مسار مشوه أو استبدال غير متوافق بدلا من المتابعة بالقيمة الأصلية.

الموافقة على الأداة وتحويل الوسيطة

تعد الموافقة على أداة إطار عمل العامل و التماس موافقة Agent Hooks آليات منفصلة. بالنسبة إلى أداة دالة مع approval_mode="always_require"، ينشئ إطار عمل العامل طلب الموافقة البشرية قبل تشغيل البرنامج الوسيط للوظيفة. pre_tool_call لذلك يمكن للتحويل تغيير الوسيطات بعد موافقة المستخدم على القيم الأصلية.

تحذير

لا تقم بتحويل الوسيطات في pre_tool_call للأدوات التي تستخدم approval_mode="always_require". قم بتحويل استدعاء الأداة في post_model_call بحيث يحتوي طلب الموافقة على إطار العمل على القيم المحولة، أو العودة Verdict.escalate(...) إلى pre_tool_call الموافقة وحلها من خلال Agent Hooks resolver.

الدفق والمثابرة

يحتفظ Agent Hooks بواجهة برمجة التطبيقات المتدفقة ولكنه يستخدم دلالات إخراج مخزنة مؤقتا. يقوم إطار عمل العامل بتجميع استجابة النموذج الكاملة، ويصدر post_model_call، ويجمع استجابة العامل النهائي، ويصدر output قبل إصدار أي تحديثات. إذا رفضت أي من النقطتين الاستجابة، فلن يتلقى المتصل أي تحديثات جزئية.

يتداول هذا السلوك زمن انتقال الرمز المميز لكل رمز مميز لإنفاذ الإخراج الذي تم إغلاقه بفشل. وينعكس تحويل الإخراج أيضا في التحديثات التي تم إصدارها في النهاية للمتصل.

يتم بوابات الثبات بواسطة نقطة الاعتراض التي تغطي عملية الثبات:

• بشكل افتراضي، ينتظر output عمل المحفوظات وغيرها من الموفرين بعد التشغيل الحكم. لا يستمر الإخراج الذي تم رفضه، ويتم استمرار تحويل الإخراج بعد التحويل.
• عند تعيين require_per_service_call_history_persistence=True على الدالة Agent الإنشائية أو client.as_agent(...)، يستمر كل تبادل نموذج بعد أن يسمح حكمه post_model_call بذلك. لا يعود الرفض اللاحق output إلى الحالة السابقة التي كانت تسمح بالمحفوظات بالفعل.
• لاستمرارية ما بعد التشغيل الافتراضية، تظل محاولات إعادة المحاولة وراء القرار النهائي output . بدلا من ذلك، يستمر وضع استدعاء لكل خدمة في كل استجابة نموذج تمر .post_model_call

Important

إذا كان يجب ألا يصبح محتوى النموذج دائما، ففرض هذا النهج عند post_model_callrequire_per_service_call_history_persistence=True. يحمي نهج الخروج للإخراج فقط ما يصل إلى المتصل، ولكنه لا يزيل تبادلات النموذج المسموح بها والمستمرة بالفعل بأثر رجعي في post_model_call.

جلسات العمل وسجلات التدقيق

بشكل افتراضي، ينشئ كل تشغيل عامل جلسة عمل Agent Hooks واحدة. agent_startup وقوس agent_shutdown التشغيل، وتتلقى السجلات معرف جلسة عمل واحد بتسلسل متزايد بشكل رتيبة.

استخدم record_sink لتلقي كل InterceptionRecord:

records = []

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

تسجل سجلات الاعتراض القرار والسبب وملخص المعترض ووضعه وهويته وتسلسله دون نسخ الحمولة المعترض عليها في سجل التدقيق. لا يزال المعترض نفسه يتلقى السياق الكامل.

امتداد عمليات تشغيل متعددة بجلسة عمل واحدة

استخدم create_agent_hooks_middleware_from_emitter() عندما يمتلك التطبيق جلسة عمل Agent Hooks أطول عمرا، مثل محادثة مع دفتر الأستاذ واحد للموافقة:

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

في هذا النموذج، يقوم التطبيق بتكوين الباعث ويمتلك بدء التشغيل وإيقاف التشغيل وتنظيف الخطأ. يصدر البرنامج الوسيط نقاط التشغيل لكل من input خلال output.

تكوين الإنفاذ

create_agent_hooks_middleware() يقبل عناصر التحكم التالية:

المعلمه	الغرض
interceptors	تسلسل من المعترضات أو تعيين الاسم إلى المعترض. مطلوب واحد على الأقل.
resolver	حل الرفض القابل للرفع من خلال قناة الموافقة. بدون محلل، يظل الرفض ساري المفعول.
mode	"enforce" تطبيق الأحكام. "evaluate_only" يسجل ما قد يحدث ولكنه يسمح بكل إجراء.
composition	تحديد كيفية دمج أحكام اعتراض متعددة.
identity_provider	ينتج هويات سياق مرتبطة بالمحتوى. الافتراضي هو "jcs-sha256".
timeout	مهلة كل اعتراض وحلل للمكالمات التي يمكن انتظارها. الإعداد الافتراضي هو خمس ثوان. لا يمكن استباق اعتراض أو محلل متزامن يحظر حلقة الحدث بواسطة هذه المهلة.
record_sink	يتلقى كل سجل اعتراض خال من الحمولة.

التكوين الافتراضي تسلسلي first_deny مع الموافقة التي تم تكوينها لإيقاف الطي. ترتيب اعتراض لذلك الأمور: وضع عناصر التحكم التي يجب تشغيلها دائما قبل عناصر التحكم التي يمكن أن تطلب الموافقة. راجع قائمة اختيار إنتاج Agent Hooks قبل تحديد ملف تعريف تكوين آخر.

طرح مع وضع التقييم فقط

استخدم evaluate_only لقياس سلوك النهج قبل الإنفاذ:

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

في هذا الوضع، يتم تشغيل المعترضين وتتضمن السجلات أحكامهم، ولكن لا يتم حظر أي إجراء أو تحويله. لا تصف evaluate_only التوزيع على أنه حوكمة مفروضة.

قواعد التكوين

ضع الحزمة أولا في قائمة البرامج الوسيطة للعامل بحيث تشكل حدود التنفيذ الخارجية:

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

اتبع هذه القواعد:

• تثبيت حزمة Agent Hooks واحدة بالضبط لكل عامل. يتم رفض الحزم المكدسة.
• حافظ على الحزمة سليمة. لا يمكن تثبيت العامل والدردشة والبرامج الوسيطة للوظيفة بشكل منفصل.
• قم بتثبيت الحزمة على Agent، وليس مباشرة على عميل دردشة أو من خلال موفر سياق.
• البرامج الوسيطة الموضوعة قبل الحزمة خارج حدود التنفيذ. تعامل مع الموضع الخارجي كثقة خارجية.
• امنح كل عامل متداخل حزمته الخاصة عندما يحتاج نموذجه الداخلي ونشاط الأداة أيضا إلى اعتراض.

القيود الحالية

• Python فقط: لم يتم تنفيذ Agent Hooks بعد في .NET أو Go SDKs.
• واجهة برمجة التطبيقات التجريبية: يمكن أن تتغير تواقيع المصنع وسلوكه قبل التوفر العام.
• الدفق المخزن مؤقتا: لا يتم إصدار التحديثات الرمز المميز بواسطة الرمز المميز لأنه يجب أن يكتمل الإخراج قبل صدور حكم بفشل مغلق.
• الأدوات المستضافة: لا تمر الأدوات التي ينفذها موفر النموذج من خلال التماس استدعاء الوظائف في Agent Framework. تظهر المكالمات والمخرجات الخاصة بهم في post_model_call، ولكن pre_tool_callpost_tool_call لا يمكن حظر تنفيذ الموفر من جانب الخادم.
• الحدود التعاونية: عامل Hooks لا يعترض بيئة الاختبار المعزولة أو يحمي من مضيف عدائي. لا تتم تغطية مسارات التعليمات البرمجية التي تتجاوز البنية الأساسية لبرنامج ربط العمليات التجارية للعامل المحمي.
• يؤثر توفر المعترض على توفر العامل: في وضع الفرض، يمنع فشل المعترض أو المهلة الإجراء المحمي حسب التصميم.

للحصول على إطلاق الإنتاج وأسباب الفشل وإرشادات التنبيه، راجع دفتر تشغيل عمليات Agent Hooks.

Agent Hooks غير متوفر بعد ل Go. استخدم البرنامج الوسيط للعاملوالموافقة على الأدواتوأمان العامل لإضافة عناصر تحكم وقت التشغيل إلى عوامل Go.

الخطوات التالية

فهم البنية الأساسية لبرنامج ربط العمليات التجارية للعامل

المحتوى ذو الصلة

• البرنامج الوسيط للعامل
• أمان العامل
• الموافقة على الأداة
• أمان العامل مع FIDES
• إمكانية المراقبة
• مواصفات AGENT-HOOKS-0.1