Most agentic AI demos look impressive. Production deployments are a different problem entirely. Agents that browse the web, write code, call APIs, and coordinate with other agents are powerful — and they fail in ways that are hard to anticipate and harder to debug.معظم عروض agentic AI تبدو مُبهِرة. النشر في الإنتاج مشكلة مختلفة تماماً. الوكلاء الذين يتصفحون الويب ويكتبون code ويستدعون APIs ويتنسقون مع وكلاء آخرين أقوياء — ويفشلون بطرق يصعب توقعها وأصعب تصحيحها.
This post covers the architecture decisions that separate brittle prototypes from systems you can actually operate.تغطي هذه المقالة القرارات المعمارية التي تفصل النماذج الأولية الهشة عن أنظمة يمكنك تشغيلها فعلاً.
What makes agentic systems differentما الذي يجعل أنظمة agentic مختلفة
A traditional API call is deterministic. You send a payload, you get a response, you handle errors. An agent loop is a feedback system: an LLM decides what tool to call, gets a result, decides what to do next, and so on for N steps until it reaches a goal or hits a limit.استدعاء API تقليدي deterministic. ترسل payload، تحصل على response، تتعامل مع الأخطاء. حلقة الوكيل نظام feedback: LLM يقرر أي أداة يستدعي، يحصل على نتيجة، يقرر التالي، وهكذا N خطوات حتى يصل للهدف أو يصل للحد.
The failure modes are different:أنماط الفشل مختلفة:
- Hallucinated tool calls — the model invents arguments or calls tools that don't exist.استدعاءات أدوات وهمية — النموذج يختلق arguments أو يستدعي أدوات غير موجودة.
- Goal drift — the agent pursues a proxy objective instead of the real one.انحراف الهدف — الوكيل يسعى لهدف proxy بدلاً من الحقيقي.
- Infinite loops — a malformed observation sends the agent into a cycle it never exits.حلقات لا نهائية — observation malformed يدخل الوكيل في دورة لا يخرج منها.
- Context window exhaustion — long conversations fill the context and degrade reasoning quality.استنفاد context window — محادثات طويلة تملأ السياق، ما يبلِّ جودة التفكير.
- Cascading failures — one bad tool call produces a bad observation that corrupts all downstream reasoning.فشل متتالي — استدعاء أداة سيئ ينتج observation سيئاً يفسد كل التفكير اللاحق.
None of these show up reliably in a five-minute demo. They show up after you've run a thousand tasks in production.لا تظهر هذه بموثوقية في عرض خمس دقائق. تظهر بعد تشغيل ألف مهمة في الإنتاج.
Design the task boundary firstصمّم حد المهمة أولاً
Before you write any agent code, define the task boundary precisely:قبل كتابة أي code للوكيل، حدّد حد المهمة بدقة:
- Entry condition — what triggers this agent, and what data is it given at start?شرط الدخول — ما الذي يشغّل هذا الوكيل، وأي بيانات يُعطى عند البداية؟
- Exit condition — what constitutes success? What constitutes a terminal failure?شرط الخروج — ما الذي يُعد نجاحاً؟ ما الذي يُعد فشلاً نهائياً؟
- Side-effect budget — which external systems can it write to, and what are the rollback paths?ميزانية side-effect — أي أنظمة خارجية يمكنه الكتابة إليها، وما مسارات rollback؟
- Escalation path — when does the agent hand off to a human?مسار escalation — متى يسلّم الوكيل لإنسان؟
Agents that lack clear exit conditions are the most common source of runaway costs. Cap token budgets, step counts, and wall-clock time independently.الوكلاء بلا شروط خروج واضحة المصدر الأكثر شيوعاً لتكاليف runaway. ضع سقفاً على token budgets وstep counts وwall-clock time بشكل مستقل.
Tool design: the hidden bottleneckتصميم الأدوات: عنق الزجاجة الخفي
The model's reasoning is only as good as the tool interfaces it calls. Poorly designed tools are the single biggest cause of agentic failures in real deployments.تفكير النموذج جيد فقط بقدر واجهات الأدوات التي يستدعيها. أدوات سيئة التصميم السبب الأكبر لفشل agentic في نشر حقيقي.
Idempotency is non-negotiable. If your agent retries a failed step (and it will), a non-idempotent tool can double-charge a customer, send a duplicate email, or create two records. Every tool the agent calls should be safe to call twice with the same arguments.Idempotency غير قابل للتفاوض. إذا أعاد الوكيل محاولة خطوة فاشلة (وسيفعل)، أداة non-idempotent قد تخصم مرتين أو ترسل email مكرر أو تنشئ سجلين. كل أداة يستدعيها الوكيل يجب أن تكون آمناً لاستدعائها مرتين بنفس arguments.
Return structured, bounded results. Don't return raw HTML from a web scrape when a structured summary is what the agent needs. Large, noisy tool responses overwhelm the context window and degrade reasoning accuracy.أعد نتائج مهيكلة ومحدودة. لا تُعد HTML خام من web scrape عندما يحتاج الوكيل ملخصاً مهيكلاً. استجابات أدوات كبيرة و noisy تغمر context window وتبلِّ دقة التفكير.
Fail loudly with context. Error messages like "500 Internal Server Error" tell the agent nothing. Error messages like "Order 7294 was not found in the staging database. Did you mean to query production?" give it a path forward.افشل بصوت عالٍ مع سياق. رسائل مثل "500 Internal Server Error" لا تخبر الوكيل شيئاً. رسائل مثل "Order 7294 was not found in the staging database. Did you mean to query production?" تعطيه مساراً للأمام.
A minimal tool schema looks like this:schema أداة minimal يبدو هكذا:
{
"name": "create_invoice",
"description": "Creates a draft invoice and returns the invoice ID. Idempotent: calling twice with the same order_id returns the existing draft.",
"parameters": {
"order_id": { "type": "string", "description": "The confirmed order ID from the orders service." },
"line_items": { "type": "array", "description": "Array of { sku, quantity, unit_price } objects." }
},
"returns": {
"invoice_id": "string",
"status": "draft | submitted | error",
"error_detail": "string | null"
}
}
Multi-agent orchestration: keep the graph flatتنسيق multi-agent: أبقِ الرسم مسطحاً
Multi-agent systems introduce coordination overhead. The temptation is to build deep hierarchies: an orchestrator spawns sub-orchestrators which spawn workers. Resist this.أنظمة multi-agent تُدخل overhead تنسيق. الإغراء بناء hierarchies عميقة: orchestrator ي spawn sub-orchestrators ي spawn workers. قاوم هذا.
Flat is easier to observe. A single orchestrator with direct connections to specialist agents is far easier to trace than a tree structure three levels deep.المسطح أسهل للمراقبة. orchestrator واحد باتصالات مباشرة مع وكلاء متخصصين أسهل بكثير للتتبع من شجرة ثلاث مستويات.
Message formats matter. Agents that communicate via structured JSON with explicit schemas degrade gracefully. Agents that pass free-form prose between each other accumulate ambiguity with every hop.تنسيقات الرسائل مهمة. وكلاء يتواصلون عبر JSON مهيكل مع schemas صريحة degrade بنعمة. وكلاء يمرّرون prose حر بينهم يتراكم ambiguity مع كل hop.
Version your agent contracts. When you upgrade the coding agent, the QA agent should not break silently. Treat inter-agent message schemas like API contracts: version them, test them, and deprecate old versions explicitly.صدّر عقود الوكلاء. عند ترقية coding agent، QA agent لا يجب أن ينكسر بصمت. عالج schemas رسائل inter-agent كعقود API: صدّرها، اختبرها، وأهمل الإصدارات القديمة صراحة.
A minimal multi-agent topology for a software delivery workflow:topology multi-agent minimal لسير عمل software delivery:
Orchestrator
├── PlanningAgent (breaks task into subtasks, returns task list)
├── CodingAgent (writes code given a spec, returns file diffs)
├── ReviewAgent (reviews diffs for correctness and security)
└── DeployAgent (applies approved diffs to staging or production)
Each agent knows only its own tools. The orchestrator holds state and routes results. No agent calls another directly.كل وكيل يعرف أدواته فقط. orchestrator يحمل state ويوجّه النتائج. لا وكيل يستدعي آخر مباشرة.
Observability: you must be able to see what happenedالمراقبة: يجب أن ترى ما حدث
Production agents need the same observability stack as any distributed system — arguably more, because the failure modes are harder to reason about.وكلاء الإنتاج يحتاجون نفس مكدس observability لأي نظام موزّع — بل أكثر، لأن أنماط الفشل أصعب استنتاجاً.
Log every LLM call with full context. Store the model version, the system prompt hash, the full message history at the time of the call, the raw response, and the latency. When something goes wrong at step 7 of a 12-step chain, you need to reconstruct exactly what the model saw.سجّل كل استدعاء LLM بسياق كامل. خزّن إصدار النموذج وhash الـ system prompt وتاريخ الرسائل الكامل وقت الاستدعاء والresponse الخام والlatency. عند خطأ في الخطوة 7 من سلسلة 12، تحتاج إعادة بناء ما رآه النموذج بالضبط.
Trace tool calls with span IDs. Each tool invocation should emit a span with: tool name, arguments (sanitized of PII), result size, latency, and success/failure. This is standard distributed tracing — just apply it to agent tool calls.تتبّع استدعاءات الأدوات بـ span IDs. كل invocation أداة يُصدِر span: اسم الأداة، arguments (منقاة من PII)، حجم النتيجة، latency، نجاح/فشل. distributed tracing قياسي — طبّقه على استدعاءات أدوات الوكيل.
Emit task-level metrics. Track success rate, mean step count, P95 latency, and token cost per task type. Sudden changes in step count often indicate a prompt regression before it appears in success rates.أصدِر metrics على مستوى المهمة. تتبّع success rate وmean step count وP95 latency وتكلفة tokens لكل نوع مهمة. تغيّرات مفاجئة في step count غالباً تشير إلى regression في prompt قبل ظهورها في success rates.
A minimal observability schema for a task run:schema observability minimal لتشغيل مهمة:
{
"task_id": "tsk_8f2c1a",
"task_type": "invoice_generation",
"start_time": "2026-01-15T10:22:44Z",
"end_time": "2026-01-15T10:22:59Z",
"steps": 6,
"input_tokens": 1840,
"output_tokens": 512,
"tool_calls": [
{ "tool": "get_order", "latency_ms": 42, "success": true },
{ "tool": "create_invoice", "latency_ms": 118, "success": true },
{ "tool": "notify_finance", "latency_ms": 31, "success": true }
],
"outcome": "success",
"error": null
}
Safety: build the guardrails before you need themالأمان: ابنِ guardrails قبل أن تحتاجها
Input validation at the agent boundary. Validate and sanitize everything before it enters an agent loop. Prompt injection — where malicious content in a tool result hijacks the agent's next action — is a real threat for agents that browse the web or process user-submitted documents.التحقق من المدخلات عند حد الوكيل. تحقّق ونقِّ كل شيء قبل دخوله حلقة الوكيل. prompt injection — حيث محتوى خبيث في نتيجة أداة يختطف الإجراء التالي — تهديد حقيقي للوكلاء التي تتصفح الويب أو تعالج مستندات مقدّمة من المستخدم.
Confirmation checkpoints for irreversible actions. Any action that writes to production, sends an external message, or costs money should require an explicit confirmation step. This can be a human-in-the-loop review or an automated policy check.نقاط تأكيد للإجراءات غير القابلة للعكس. أي إجراء يكتب في الإنتاج أو يرسل رسالة خارجية أو يكلف مالاً يجب أن يتطلب خطوة تأكيد صريحة. human-in-the-loop أو فحص policy آلي.
Hard resource limits, not soft warnings. Max tokens: hard stop. Max steps: hard stop. Max API spend per task: hard stop. Soft limits that emit warnings are ignored in production under load.حدود موارد صلبة، لا تحذيرات ناعمة. Max tokens: إيقاف صلب. Max steps: إيقاف صلب. Max API spend لكل مهمة: إيقاف صلب. حدود ناعمة تُصدِر تحذيرات تُتجاهل في الإنتاج تحت الحمل.
Audit logs are not optional. Every state transition, every tool call, every decision point should be logged to an immutable store. When regulators or customers ask "what did the agent do and why", you need a complete answer.سجلات التدقيق ليست اختيارية. كل انتقال state وكل استدعاء أداة وكل نقطة قرار يجب أن تُسجَّل في مخزن immutable. عندما يسأل منظمون أو عملاء «ماذا فعل الوكيل ولماذا»، تحتاج إجابة كاملة.
The operational checklistقائمة التحقق التشغيلية
Before moving an agentic system from staging to production:قبل نقل نظام agentic من staging إلى الإنتاج:
- [ ] Every tool is idempotent and tested with duplicate calls[ ] كل أداة idempotent ومُختبرة باستدعاءات مكررة
- [ ] Hard limits on tokens, steps, and wall-clock time are enforced[ ] حدود صلبة على tokens وsteps وwall-clock time مُفرَضة
- [ ] Distributed tracing is in place for all tool calls[ ] distributed tracing مفعّل لكل استدعاءات الأدوات
- [ ] Full LLM call logs are stored for at least 30 days[ ] سجلات استدعاء LLM كاملة محفوظة 30 يوماً على الأقل
- [ ] Prompt injection surfaces have been tested with adversarial inputs[ ] أسطح prompt injection مُختبرة بمدخلات adversarial
- [ ] There is a kill switch that stops all running tasks within 60 seconds[ ] kill switch يوقف كل المهام الجارية خلال 60 ثانية
- [ ] Escalation paths to humans are defined and tested[ ] مسارات escalation للبشر معرّفة ومُختبرة
- [ ] Task-level cost accounting is in place[ ] محاسبة تكلفة على مستوى المهمة مفعّلة
Agentic AI is a genuinely powerful paradigm. But it is a distributed system with a non-deterministic component at its core — and it deserves the same engineering discipline as any other system you'd run in production.agentic AI نموذج قوي فعلاً. لكنه نظام موزّع بمكوّن non-deterministic في قلبه — ويستحق نفس الانضباط الهندسي لأي نظام تشغّله في الإنتاج.
Related: explore more under Agentic AI & Multi-Agent Systems on the insights hub.ذات صلة: استكشف المزيد تحت Agentic AI & Multi-Agent Systems في مركز الرؤى.