Je eerste agent

Wat je gaat bouwen

Een complete, uitvoerbare Agent-Lab-applicatie: een FastAPI-service die een echo-agent host, een MCP-server, persistentie in PostgreSQL en instrumentatie met OpenTelemetry — allemaal gescaffold met één commando, niets met de hand gekoppeld. Onderweg maak je via REST een agentinstantie aan, stuur je die een bericht en bekijk je de traces van het framework.

Vereisten

• Python 3.12+ en uv (pip install uv)
• Docker (of een andere container-runtime), actief

Voor deze tutorial heb je geen API-sleutels nodig — de echo-agent roept geen LLM aan. Agents op basis van een LLM komen hierna (zie Hoe verder?).

1. Het project scaffolden

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

Beantwoord de vragen — met de standaardwaarden krijg je een project met de naam My Agent App:

cd my-agent-app

De scaffold is een dunne consumer van het framework, geen fork. btech-agent-lab is een gewone afhankelijkheid in pyproject.toml; je code staat ernaast en breidt het uit via de publieke API.

2. Begrijpen wat je hebt gekregen

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

Open my_agent_app/main.py — dit is de hele applicatie:

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

En my_agent_app/agents/echo/agent.py — de agent zelf:

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

Twee dingen om op te letten:

• @discoverable_agent("my_agent_app_echo") — die ene decorator registreert de klasse onder een agent_type. Geen aanpassingen aan het register, geen schemawijzigingen: de REST API valideert agent_type dynamisch tegen het register.
• AgentUtils wordt geïnjecteerd via de constructor door de DI-container. Declareer meer afhankelijkheden met extra_deps=("my_provider",) en voeg bijpassende providers toe aan core/container.py (zie de Handleiding voor ontwikkelaars).

3. Testen voordat je het uitvoert

De unittests van de scaffold starten de hele applicatie op zonder enige infrastructuur:

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

Je krijgt ook de integratievariant — make test_integration start echte Postgres-, Redis- en Vault-containers via testcontainers (Docker vereist).

4. De app uitvoeren

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

De stack bestaat uit de app (poort 18000), PostgreSQL met pgvector (drie databases: relationeel, vectoren, LangGraph-checkpoints), Redis voor pub/sub-statusupdates en Vault voor secrets. De interactieve OpenAPI-documentatie vind je op http://localhost:18000/docs.

Authenticatie is uitgeschakeld in de scaffold (auth.enabled: false). Als je die inschakelt, heeft elk request een bearer-token nodig — zie Authenticatie met Keycloak.

5. Via REST met je agent praten

Agents zijn instanties van een implementatie, die via de API worden aangemaakt en geconfigureerd. Maak er een aan:

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

Kopieer de id uit de response en stuur de agent daarna een bericht:

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

Het antwoord komt synchroon terug:

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

Die round-trip heeft de hele stack doorlopen: REST-request → opzoeken in het register → DI-container → je agent → opslaan van het bericht (en het antwoord wordt ook opgeslagen — controleer POST /messages/list). De volledige catalogus staat in de REST API-referentie.

6. De trace bekijken

De observability van Agent-Lab is gewoon OpenTelemetry. Als de omgevingsvariabele OTEL_EXPORTER_OTLP_ENDPOINT is ingesteld, exporteert de app OTLP-traces/-metrics/-logs; als die niet is ingesteld, staat tracing gewoon uit — in beide gevallen zonder codewijzigingen.

Start de meegeleverde Grafana-stack van het framework (vanuit de repository van het framework) en laat je app naar de collector ervan wijzen:

# 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

Stuur nog een bericht, open dan Grafana op http://localhost:3000 (admin/admin) en verken het Agent-Lab-dashboard: de HTTP-span, de SQL-query's en — bij agents op basis van een LLM — elke modelaanroep met het aantal tokens. Heb je liever een gehost platform voor LLM-observability? Stel dan LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY (of LANGWATCH_ENDPOINT/ LANGWATCH_API_KEY) in — details in de handleiding Observability.

7. Kennismaken in een MCP-client

De scaffold bevat al een MCP-tool (my_agent_app/mcp/tools.py), beschikbaar op /mcp, naast de tools van het framework voor het ontdekken van agents, geschiedenis en berichten. Probeer het met de MCP Inspector:

npx @modelcontextprotocol/inspector

Maak verbinding met http://localhost:18000/mcp (Streamable HTTP), toon de tools en roep my_agent_app_hello_tool aan. Dezelfde server werkt met Claude Desktop en elke MCP-client — zie de Handleiding MCP-server.

Hoe verder?