Ihr erster Agent

Was Sie entwickeln werden

Eine vollständige, lauffähige Agent-Lab-Anwendung: einen FastAPI-Service, der einen Echo-Agenten, einen MCP-Server, PostgreSQL-Persistenz und OpenTelemetry-Instrumentierung bereitstellt – alles mit einem einzigen Befehl per Scaffolding erzeugt, nichts davon manuell verdrahtet. Unterwegs erstellen Sie eine Agent-Instanz per REST, senden ihr eine Nachricht und verfolgen die Traces des Frameworks.

Voraussetzungen

• Python 3.12+ und uv (pip install uv)
• Docker (oder eine andere Container-Runtime), gestartet

Für dieses Tutorial sind keine API-Schlüssel erforderlich – der Echo-Agent ruft kein LLM auf. LLM-gestützte Agenten folgen als Nächstes (siehe Wie geht es weiter?).

1. Das Projekt per Scaffolding erstellen

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

Beantworten Sie die Abfragen – mit den Standardwerten erhalten Sie ein Projekt namens My Agent App:

cd my-agent-app

Das Scaffold ist ein schlanker Nutzer des Frameworks, kein Fork. btech-agent-lab ist eine reguläre Abhängigkeit in pyproject.toml; Ihr Code liegt daneben und erweitert das Framework über die öffentliche API.

2. Verstehen, was Sie erhalten haben

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

Öffnen Sie my_agent_app/main.py – das ist die gesamte Anwendung:

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

Und my_agent_app/agents/echo/agent.py – der Agent selbst:

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

Zwei Dinge sind bemerkenswert:

• @discoverable_agent("my_agent_app_echo") – dieser eine Decorator registriert die Klasse unter einem agent_type. Keine Änderungen an der Registry, keine Schemaänderungen: Die REST API validiert agent_type dynamisch gegen die Registry.
• AgentUtils wird injiziert – über den Konstruktor durch den DI-Container. Deklarieren Sie weitere Abhängigkeiten mit extra_deps=("my_provider",) und fügen Sie passende Provider zu core/container.py hinzu (siehe Entwicklerhandbuch).

3. Testen, bevor Sie ausführen

Die Unit-Tests des Scaffolds starten die gesamte Anwendung ganz ohne Infrastruktur:

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

Die Integrationsvariante erhalten Sie ebenfalls – make test_integration startet echte Postgres-, Redis- und Vault-Container über testcontainers (Docker erforderlich).

4. Die Anwendung ausführen

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

Der Stack besteht aus der Anwendung (Port 18000), PostgreSQL mit pgvector (drei Datenbanken: relational, Vektoren, LangGraph-Checkpoints), Redis für Pub/Sub-Statusupdates und Vault für Secrets. Die interaktive OpenAPI-Dokumentation finden Sie unter http://localhost:18000/docs.

Die Authentifizierung ist im Scaffold deaktiviert (auth.enabled: false). Wenn Sie sie aktivieren, benötigt jeder Request ein Bearer-Token – siehe Authentifizierung mit Keycloak.

5. Per REST mit Ihrem Agenten kommunizieren

Agenten sind Instanzen einer Implementierung, die über die API erstellt und konfiguriert werden. Erstellen Sie eine:

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

Kopieren Sie die id aus der Response und senden Sie dann eine Nachricht:

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

Die Antwort kommt synchron zurück:

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

Dieser Roundtrip hat den gesamten Stack durchlaufen: REST-Request → Registry-Lookup → DI-Container → Ihr Agent → Persistierung der Nachricht (auch die Antwort wird gespeichert – prüfen Sie POST /messages/list). Den vollständigen Katalog finden Sie in der REST-API-Referenz.

6. Den Trace verfolgen

Die Observability von Agent-Lab ist schlicht OpenTelemetry. Wenn die Umgebungsvariable OTEL_EXPORTER_OTLP_ENDPOINT gesetzt ist, exportiert die Anwendung OTLP-Traces/-Metriken/-Logs; ist sie nicht gesetzt, ist das Tracing einfach deaktiviert – in keinem Fall sind Codeänderungen nötig.

Starten Sie den mitgelieferten Grafana-Stack des Frameworks (aus dem Framework-Repository) und richten Sie Ihre Anwendung auf dessen Collector aus:

# 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

Senden Sie eine weitere Nachricht, öffnen Sie dann Grafana unter http://localhost:3000 (admin/admin) und erkunden Sie das Dashboard Agent-Lab: den HTTP-Span, die SQL-Abfragen und – bei LLM-gestützten Agenten – jeden Modellaufruf mit Token-Anzahl. Sie bevorzugen eine gehostete LLM-Observability-Plattform? Setzen Sie stattdessen LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY (oder LANGWATCH_ENDPOINT/ LANGWATCH_API_KEY) – Details im Observability-Guide.

7. Den Agenten in einem MCP-Client nutzen

Das Scaffold bringt bereits ein MCP-Tool (my_agent_app/mcp/tools.py) mit, das unter /mcp bereitgestellt wird – neben den Tools des Frameworks für Agent-Discovery, Verlauf und Messaging. Probieren Sie es mit dem MCP Inspector aus:

npx @modelcontextprotocol/inspector

Verbinden Sie sich mit http://localhost:18000/mcp (Streamable HTTP), listen Sie die Tools auf und rufen Sie my_agent_app_hello_tool auf. Derselbe Server funktioniert mit Claude Desktop und jedem MCP-Client – siehe den MCP-Server-Guide.

Wie geht es weiter?