LlamaIndex

التثبيت

pip install 'failproofai-sdk[llamaindex]'

مدعوم: llama-index-core 0.14.23 إلى 0.15. 0.14.23 هو الإصدار حيث بدأ تدفق سير العمل بنقل أحداث الوكيل المكتوبة بشكل صريح التي يقرأها هذا المحول. تحته، تختفي أسماء النموذج وهيكل الوكيل معاً.

الضبط

import asyncio

import failproofai_sdk

failproofai_sdk.configure(environment="production")
failproofai_sdk.instrument()

async def main():
    async with failproofai_sdk.session():
        await agent.run("...")

asyncio.run(main())

واجهة برمجة التطبيقات للوكيل في LlamaIndex غير متزامنة. كل نطاق يعمل تحت async with وكذلك with وينتج أحداثاً متطابقة. instrument() تربط معالج حدث ومعالج امتداد لموزع LlamaIndex العام. معاً يجعلان حلقة الوكيل مرئية، وليس فقط استدعاءات نموذجه.

بدون وسيطة إضافية على نموذجك، كل عدد رموز في تتبعك قيمته null. انظر عدد الرموز أدناه.

عدد الرموز

FunctionAgent يستدعي astream_chat، وllama-index-llms-openai لا يرسل stream_options={"include_usage": True} عند البث. المزود بالتالي لا يرسل أبداً مقطع الاستخدام، ولا شيء لأي أداة ضبط لقراءته. هذا سلوك LlamaIndex الأساسي. قم بالاشتراك في نموذجك:

from llama_index.llms.openai import OpenAI

llm = OpenAI(
    model="gpt-4o-mini",
    additional_kwargs={"stream_options": {"include_usage": True}},
)

تم القياس في نفس التشغيل والنموذج:

	رموز الإدخال	رموز الإخراج
بدون	`null`	`null`
مع	148	17

استدعاءات البث غير المتزامن (llm.chat, llm.achat) تقرر الاستخدام بدون تكوين. فقط مسار البث، وهو المسار الافتراضي للوكيل، يحتاج إلى هذا.

ما يتم تسجيله

LlamaIndex	حدث Failproof
`Workflow.run` امتداد الجذر	جلسة، `agent_start`، `agent_end`
امتداد `Workflow.run` المتداخل	`agent_start` متداخل، `agent_end`
امتداد خطوة سير العمل	`hook_triggered`، `hook_completed`
بداية ونهاية دردشة LLM	`model_request`، `model_response`
امتداد `FunctionTool.call`	`tool_use`، `tool_result`
بداية ونهاية الاسترجاع	`tool_use`، `tool_result`، الناتج المختصر
التضمينات	لا شيء، إلا إذا كان `embeddings=True`
أداة تنتظر شخصاً	`human_wait`، `agent_pause`، ثم `agent_resume`، `human_input`
مسلمة `AgentWorkflow`	`agent_start` متداخل، `agent_end` لكل وكيل، مرتبط بسير العمل
الاستثناء	`error`، ثم `agent_end` مع النتيجة `failed`، و`agent_end.summary` يسميها
`handler.cancel_run()`	`agent_end` مع النتيجة `cancelled` وبدون `error` — زر الإيقاف ليس فشلاً

agent_id هو FunctionAgent.name عندما تحدده، واسم فئة سير العمل وإلا. تحت AgentWorkflow، كل وكيل يأخذ دوره يحصل على امتداده الخاص المتداخل تحت سير العمل، لذا تُقرأ المسلمة كوكيلين بدلاً من واحد. الناتج من الاسترجاع مختصر بدلاً من أن يُرمى. يعيد المسترجع المستندات، وتخزينها في الحمل سيضع مجموعة النصوص الخاصة بك في مخزن الأحداث مرة واحدة لكل استعلام. يتم الاحتفاظ بالعدد، نطاق النقاط، والمقاطع المختصرة بدلاً من ذلك.

مثال

import asyncio

import failproofai_sdk
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI

failproofai_sdk.configure(environment="production")
failproofai_sdk.instrument()

POP = {"tokyo": "37M", "delhi": "33M"}
AREA = {"tokyo": "2,194 km2", "delhi": "1,484 km2"}


def population(city: str) -> str:
    """Population of a city. Valid: tokyo, delhi."""
    return POP.get(city.lower().strip(), "unknown")


def area(city: str) -> str:
    """Land area of a city. Valid: tokyo, delhi."""
    return AREA.get(city.lower().strip(), "unknown")


async def main():
    agent = FunctionAgent(
        name="city_analyst",
        tools=[
            FunctionTool.from_defaults(fn=population),
            FunctionTool.from_defaults(fn=area),
        ],
        llm=OpenAI(
            model="gpt-4o-mini",
            additional_kwargs={"stream_options": {"include_usage": True}},
        ),
        system_prompt="Use the tools. Be terse.",
    )

    async with failproofai_sdk.session():
        async with failproofai_sdk.agent("city_analyst", goal="compare two cities"):
            print(await agent.run("Compare Tokyo and Delhi on population and area."))


asyncio.run(main())

تظهر حلقة الوكيل في التتبع كأزواج hook: init_run، setup_agent، run_agent_step، parse_agent_output، call_tool، وaggregate_tool_results. إنها حلقة الإطار نفسه، لذا فهي hooks بدلاً من وكلاء، مما يحافظ على معنى agent_id.

سمِّ امتدادك

agent_id هو FunctionAgent.name عندما تحدده، واسم فئة سير العمل وإلا.

FunctionAgent(name="city_analyst", tools=[...], llm=llm)   # agent_id = "city_analyst"

في AgentWorkflow، هذا الاسم هو أيضاً ما يتم تسجيل كل مسلمة تحته:

AgentWorkflow            امتداد الأب
├─ city_analyst          الدور 1
├─ cost_analyst          الدور 2
└─ city_analyst          الدور 3  — دور جديد، وليس دور معاد فتحه

إذاً agent_id يخبرك أي وكيل قام بالعمل وparent_id يخبرك أي سير عمل انتمى إليه. يفتح الوكيل الذي يسلم التحكم لاحقاً دوره الثاني بدلاً من إعادة فتح الأول. لف التشغيل لتجاوزه، أو لتجميع عدة وكلاء تحت أب واحد:

async with failproofai_sdk.agent("research", goal="compare two cities"):
    await agent.run(...)

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

تحكم في الجلسة

هذا المحول لا يأخذ خيار session_id. تأتي الجلسة من النطاق المحيط، وإلا uuid4().hex مُولدة لكل تشغيل سير عمل:

async with failproofai_sdk.session(f"chat-{user_id}"):
    await agent.run(...)

الخيارات

failproofai_sdk.instrument(
    "llama_index",
    embeddings=False,         # True يسجل استدعاءات التضمين كأزواج أدوات
    steps=True,               # False يسقط أزواج hook خطوة سير العمل
    capture_messages=True,    # False يسقط EVERY الحمل: المحفزات، الإكمالات،
                              # وسائط الأداة والناتج، إدخال وإخراج الخطوة، استعلامات
                              # الاسترجاع، الهدف والإجابة النهائية
    capture_limit=8192,       # الأحرف المحتفظ بها لكل قيمة مقبوضة
    stale_after=600.0,        # ثواني قبل إغلاق أوراق الشجر المهجورة بقوة
    reaper_interval=30.0,     # عدد مرات كنس الحاصد؛ 0 يعطله
)

الخيار	لماذا قد تغيره
`embeddings`	قم بالتشغيل فقط عند تصحيح كمون أو تكلفة التضمين. بناء فهرس مجموعي هو آلاف الاستدعاءات وسيدفن المخطط الزمني.
`steps`	أطفئه إذا كنت تريد فقط أحداث النموذج والأداة وتجد حلقة الوكيل مزعجة.
`capture_messages`	أطفئه للبيانات المنظمة. كل حمل يتوقف عن التسجيل — المحفزات، إكمال النموذج، وسائط الأداة وقيم الإرجاع، إدخال وإخراج خطوة سير العمل، استعلامات الاسترجاع، هدف الوكيل وإجابته النهائية. الهيكل والتوقيتات والرموز والنتائج لا تزال مسجلة.
`capture_limit`	الأحرف المحتفظ بها لكل قيمة مقبوضة قبل الاقتطاع. ارفعه عندما يصل محفز RAG أو السياق المسترجع مقطوعاً.
`stale_after`	الثواني قبل إغلاق ورقة شجر مهجورة بقوة — استجابة بث لم يستهلكها أحد، امتداد نموذج أو أداة لم يصل إغلاقه — بحيث تستقر الجلسة بدلاً من قراءة `ongoing` للأبد. هذا لا يغلق التشغيل المهجور نفسه: سير عمل تم إلغاء مهمته دون أن يرى الموزع مخرجاً يحتفظ بـ `agent_start` مفتوح حتى `uninstrument()`.
`reaper_interval`	تكرار المسح. اضبطه على `0` لتعطيل الحاصد كلياً.

الإنسان في الحلقة

يتم الالتقاط عند حدوث الانتظار داخل أداة:

async def ask_human(question: str) -> str:
    """Ask a person and wait for their answer."""
    response = await ctx.wait_for_event(HumanResponseEvent)
    return response.answer

ctx.wait_for_event في خطوة سير عمل عادية لا يتم التقاطها. يمسك وقت التشغيل بالقطرة قبل وصولها للموزع، لذا تخرج الخطوة وتعاد لاحقاً بدون إشارة لمفتاح الإيقاف عليها. نمط FunctionAgent، الذي توثقه LlamaIndex، ينتظر داخل أداة ويتم التقاطه بالكامل.

مشاكل شائعة

كل عدد رموز قيمته null

أضف additional_kwargs={"stream_options": {"include_usage": True}} إلى نموذجك. انظر عدد الرموز.

الاستخدام مملوء لكن أعمدة الرموز فارغة

LlamaIndex لا يملك حقل استخدام قياسي. يحاول المحول عدة أشكال معروفة، والتكامل الذي يسمي العدادات الخاصة به بشيء جديد لن يطابق أي منها.يشحن القاموس الخام دائماً، لذا تحقق من usage في الحمل لترى ما سماه مزودك.usage مملوء بجانب أعمدة رموز فارغة مقصود — يفوق عدداً خاطئاً واثقاً.

المخطط الزمني ممتلئ بـ setup_agent و parse_agent_output

هذه حلقة FunctionAgent، مجموعة واحدة لكل تكرار. صفِّ حسب اسم hook على لوحة المعلومات. توقيتات الخطوة هذه عادة ما تكون السبب لاستخدام هذا المحول بدلاً من محول نموذج فقط.

لا شيء مسجل

تحقق بهذا الترتيب: instrument() تم تشغيله قبل التشغيل؛ هناك async with failproofai_sdk.session(): حول await؛ llama-index-core هو 0.14.23 أو أحدث؛ FAILPROOFAI_SDK_STRICT=1 مضبوط، لذا يرفع hook متدهور بدلاً من أن يبتلع.

كيف يعمل

الأزواج والمعرفات ودورة حياة الجلسة والتسليم.

اقرأ تتبعاً

اتبع السببية عبر الجلسة التي استقطتها للتو.

أطر عمل أخرى

LangGraph، CrewAI، Pydantic AI، والوكلاء المخصصين.

Understand every run

Plug in your agent

التثبيت

الضبط

عدد الرموز

ما يتم تسجيله

مثال

سمِّ امتدادك

تحكم في الجلسة

الخيارات

الإنسان في الحلقة

مشاكل شائعة

التالي

كيف يعمل

اقرأ تتبعاً

أطر عمل أخرى

​التثبيت

​الضبط

​عدد الرموز

​ما يتم تسجيله

​مثال

​سمِّ امتدادك

​تحكم في الجلسة

​الخيارات

​الإنسان في الحلقة

​مشاكل شائعة

​التالي

كيف يعمل

اقرأ تتبعاً

أطر عمل أخرى

التثبيت

الضبط

عدد الرموز

ما يتم تسجيله

مثال

سمِّ امتدادك

تحكم في الجلسة

الخيارات

الإنسان في الحلقة

مشاكل شائعة

التالي