وكيلك الأول

ما الذي ستبنيه

تطبيق Agent-Lab كامل وقابل للتشغيل: خدمة FastAPI تستضيف وكيل صدى (echo)، وخادم MCP، وتخزيناً دائماً في PostgreSQL، وأدوات رصد OpenTelemetry — وكل ذلك يُنشأ بأمر واحد، دون أي ربط يدوي. وخلال ذلك ستنشئ نسخة وكيل عبر REST، وترسل إليها رسالة، وتتابع تتبّعات الإطار.

المتطلبات الأساسية

• Python 3.12+ وuv (pip install uv)
• Docker (أو بيئة تشغيل حاويات أخرى) قيد التشغيل

لا حاجة إلى أي مفاتيح API في هذا الدرس — فوكيل الصدى لا يستدعي LLM. أما الوكلاء المعتمدون على LLM فتأتي لاحقاً (راجع ما الخطوة التالية؟).

1. أنشئ هيكل المشروع

uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter

أجب عن الأسئلة — تمنحك القيم الافتراضية مشروعاً باسم My Agent App:

cd my-agent-app

الهيكل المُولَّد مستهلك خفيف للإطار، وليس نسخة متفرعة (fork) منه. إذ إن btech-agent-lab تبعية عادية في pyproject.toml؛ وتعيش شيفرتك إلى جانبها وتوسّعها عبر الواجهة البرمجية العامة.

2. تعرّف على ما حصلت عليه

my-agent-app/
├── my_agent_app/
│   ├── main.py              # the composition root — one create_app() call
│   ├── core/container.py    # your DI container — add providers here
│   ├── agents/echo/agent.py # your first agent (echo)
│   └── mcp/tools.py         # your first MCP tool
├── config-dev.yml / config-test.yml / config-docker.yml
├── tests/                   # unit tests (no infra) + optional testcontainers suite
├── compose.yml              # app + postgres (pgvector) + redis + vault
└── Makefile, docker/, .github/, pyproject.toml

افتح my_agent_app/main.py — هذا هو التطبيق بأكمله:

from agent_lab import create_app

from my_agent_app.core.container import Container

# An explicit scan_packages list replaces agent_lab's DEFAULT_SCAN_PACKAGES:
# only this project's agents, MCP tools, and prompts are discovered — none of
# the framework's built-in examples. Add "agent_lab.services.agent_types" or
# "agent_lab.interface.mcp" here if you want the built-ins back.
app = create_app(
    container=Container(),
    scan_packages=[
        "my_agent_app.agents",
        "my_agent_app.mcp",
    ],
)

وmy_agent_app/agents/echo/agent.py — الوكيل نفسه:

from langchain_core.messages import AIMessage
from langgraph.graph import MessagesState

from agent_lab import AgentBase, AgentUtils, discoverable_agent
from agent_lab.interface.api.messages.schema import Message, MessageRequest
from agent_lab.services.tasks import TaskProgress


@discoverable_agent("my_agent_app_echo")
class EchoAgent(AgentBase):
    """Minimal agent: echoes the incoming message without calling an LLM."""

    def __init__(self, agent_utils: AgentUtils):
        super().__init__(agent_utils)

    def create_default_settings(self, agent_id: str, schema: str):
        pass

    def get_input_params(self, message_request: MessageRequest, schema: str) -> dict:
        return message_request.model_dump()

    def process_message(self, message_request: MessageRequest, schema: str) -> Message:
        message_content, response_data = self.format_response(
            MessagesState(
                messages=[AIMessage(content=f"Echo: {message_request.message_content}")]
            )
        )

        self.task_notification_service.publish_update(
            task_progress=TaskProgress(
                agent_id=message_request.agent_id,
                status="completed",
                message_content=message_content,
                response_data=response_data,
            )
        )

        return Message(
            message_role="assistant",
            message_content=message_content,
            response_data=response_data,
            agent_id=message_request.agent_id,
        )

أمران جديران بالملاحظة:

• @discoverable_agent("my_agent_app_echo") — يسجّل هذا المُزخرِف الوحيد الفئة تحت agent_type. لا تعديلات على السجل، ولا تغييرات في المخطط: إذ تتحقق REST API من agent_type مقابل السجل ديناميكياً.
• يُحقن AgentUtils عبر المُنشئ (constructor) بواسطة حاوية DI. صرّح عن مزيد من التبعيات باستخدام extra_deps=("my_provider",) وأضف المزوّدات المقابلة إلى core/container.py (راجع دليل المطوّر).

3. اختبره قبل تشغيله

تُقلع اختبارات الوحدة في الهيكل المُولَّد التطبيقَ بأكمله دون أي بنية تحتية على الإطلاق:

uv lock && uv sync --group dev --group test
make test_unit

وتحصل على نسخة اختبارات التكامل أيضاً — إذ يشغّل make test_integration حاويات Postgres وRedis وVault حقيقية عبر testcontainers (يتطلب Docker).

4. شغّل التطبيق

docker compose up --build -d
curl http://localhost:18000/status/liveness

تتكوّن الحزمة من التطبيق (المنفذ 18000)، وPostgreSQL مع pgvector (ثلاث قواعد بيانات: علائقية، ومتّجهات، ونقاط حفظ LangGraph)، وRedis لتحديثات الحالة عبر pub/sub، و Vault للأسرار. ويتوفر توثيق OpenAPI التفاعلي على http://localhost:18000/docs.

المصادقة معطّلة في الهيكل المُولَّد (auth.enabled: false). وعند تفعيلها، يحتاج كل طلب إلى رمز bearer — راجع المصادقة باستخدام Keycloak.

5. تحدّث إلى وكيلك عبر REST

الوكلاء نسخ من تنفيذ ما، تُنشأ وتُضبط عبر الواجهة البرمجية. أنشئ واحداً:

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-first-agent", "agent_type": "my_agent_app_echo"}' | jq

انسخ قيمة id من الاستجابة، ثم أرسل إليه رسالة:

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "<agent_id>",
        "message_role": "human",
        "message_content": "Hello, framework!"
      }' | jq

يصل الرد بشكل متزامن:

{
  "message_role": "assistant",
  "message_content": "Echo: Hello, framework!",
  "agent_id": "<agent_id>",
  "id": "…"
}

اختبرت هذه الرحلة ذهاباً وإياباً الحزمة بأكملها: طلب REST → البحث في السجل → حاوية DI → وكيلك → تخزين الرسالة (ويُخزَّن الرد أيضاً — تحقّق عبر POST /messages/list). الكتالوج الكامل متاح في مرجع REST API.

6. تابع التتبّع

قابلية المراقبة في Agent-Lab ليست سوى OpenTelemetry. عند ضبط متغير البيئة OTEL_EXPORTER_OTLP_ENDPOINT، يصدّر التطبيق التتبّعات/المقاييس/السجلات عبر OTLP؛ وعند عدم ضبطه، يكون التتبّع متوقفاً ببساطة — دون أي تغييرات في الشيفرة في الحالتين.

شغّل حزمة Grafana المضمّنة في الإطار (من مستودع الإطار) ووجّه تطبيقك إلى المُجمِّع الخاص بها:

# In the agent-lab framework repo — collector on :4318, Grafana UI on :3000
docker compose -f compose-grafana.yml up --build

# Back in your project — restart the app with the endpoint set
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 docker compose up --build -d

أرسل رسالة أخرى، ثم افتح Grafana على http://localhost:3000 (admin/admin) واستكشف لوحة المعلومات Agent-Lab: الـ span الخاص بـ HTTP، واستعلامات SQL، و— للوكلاء المعتمدين على LLM — كل استدعاء للنموذج مع عدد الرموز. هل تفضّل منصة مستضافة لقابلية مراقبة LLM؟ اضبط LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY (أو LANGWATCH_ENDPOINT/ LANGWATCH_API_KEY) بدلاً من ذلك — التفاصيل في دليل قابلية المراقبة.

7. قابله في عميل MCP

يأتي الهيكل المُولَّد مسبقاً مع أداة MCP (my_agent_app/mcp/tools.py) متاحة على /mcp، إلى جانب أدوات الإطار لاكتشاف الوكلاء والسجل والمراسلة. جرّبها باستخدام MCP Inspector:

npx @modelcontextprotocol/inspector

اتصل بـ http://localhost:18000/mcp (Streamable HTTP)، واعرض قائمة الأدوات، واستدعِ my_agent_app_hello_tool. يعمل الخادم نفسه مع Claude Desktop ومع أي عميل MCP — راجع دليل خادم MCP.

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