הסוכן הראשון שלך

מה נבנה

אפליקציית Agent-Lab שלמה ומוכנה להרצה: שירות FastAPI שמארח סוכן echo, שרת MCP, שמירת נתונים ב-PostgreSQL ואינסטרומנטציה של OpenTelemetry — הכול נוצר בפקודה אחת, בלי חיווט ידני. בדרך ניצור מופע של סוכן דרך REST, נשלח אליו הודעה ונצפה ב-traces של הפריימוורק.

דרישות מוקדמות

• Python 3.12+ ו-uv (pip install uv)
• Docker (או סביבת הרצה אחרת לקונטיינרים), במצב פעיל

אין צורך במפתחות API בהדרכה זו — סוכן ה-echo אינו קורא ל-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; הקוד שלך יושב לצדה ומרחיב אותה דרך ה-API הציבורי.

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 מוזרק דרך הבנאי על ידי קונטיינר ה-DI. אפשר להצהיר על תלויות נוספות עם extra_deps=("my_provider",) ולהוסיף providers תואמים ל-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 (שלושה מסדי נתונים: רלציוני, וקטורים ו-checkpoints של LangGraph), Redis לעדכוני סטטוס ב-pub/sub, ו-Vault לסודות. התיעוד האינטראקטיבי של OpenAPI זמין בכתובת http://localhost:18000/docs.

האימות מושבת בשלד (auth.enabled: false). לאחר הפעלתו, כל בקשה דורשת bearer token — ראו אימות עם Keycloak.

5. שיחה עם הסוכן דרך REST

סוכנים הם מופעים של מימוש, שנוצרים ומוגדרים דרך ה-API. יוצרים אחד:

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. צפייה ב-trace

הניטור של Agent-Lab הוא פשוט OpenTelemetry. כשמשתנה הסביבה OTEL_EXPORTER_OTLP_ENDPOINT מוגדר, האפליקציה מייצאת traces/metrics/logs בפורמט OTLP; כשהוא אינו מוגדר, ה-tracing פשוט כבוי — ובשני המקרים אין צורך בשינויי קוד.

מריצים את סביבת Grafana המצורפת לפריימוורק (מתוך מאגר הפריימוורק) ומפנים את האפליקציה ל-collector שלה:

# 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.

מה הלאה?