Twój pierwszy agent

Co zbudujesz

Kompletną, gotową do uruchomienia aplikację Agent-Lab: usługę FastAPI hostującą agenta echo, serwer MCP, persystencję w PostgreSQL i instrumentację OpenTelemetry — wszystko wygenerowane jednym poleceniem, bez ręcznego łączenia czegokolwiek. Po drodze utworzysz instancję agenta przez REST, wyślesz do niej wiadomość i obejrzysz ślady generowane przez framework.

Wymagania wstępne

• Python 3.12+ oraz uv (pip install uv)
• Uruchomiony Docker (lub inne środowisko uruchomieniowe kontenerów)

Ten samouczek nie wymaga żadnych kluczy API — agent echo nie wywołuje LLM. Agenci oparci na LLM pojawiają się w kolejnym kroku (zobacz Co dalej?).

1. Wygeneruj szkielet projektu

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

Odpowiedz na pytania — wartości domyślne dają projekt o nazwie My Agent App:

cd my-agent-app

Wygenerowany szkielet jest cienkim konsumentem frameworka, a nie jego forkiem. btech-agent-lab jest zwykłą zależnością w pyproject.toml; twój kod znajduje się obok i rozszerza framework przez publiczne API.

2. Zobacz, co otrzymałeś

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

Otwórz my_agent_app/main.py — to cała aplikacja:

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

Oraz my_agent_app/agents/echo/agent.py — sam agent:

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

Zwróć uwagę na dwie rzeczy:

• @discoverable_agent("my_agent_app_echo") — ten jeden dekorator rejestruje klasę pod typem agent_type. Bez edycji rejestru i bez zmian schematu: REST API dynamicznie waliduje agent_type względem rejestru.
• AgentUtils jest wstrzykiwany przez konstruktor za pomocą kontenera DI. Kolejne zależności deklarujesz przez extra_deps=("my_provider",), a odpowiadających im providerów dodajesz w core/container.py (zobacz Przewodnik programisty).

3. Przetestuj, zanim uruchomisz

Testy jednostkowe szkieletu uruchamiają całą aplikację bez jakiejkolwiek infrastruktury:

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

Dostajesz też wariant integracyjny — make test_integration uruchamia prawdziwe kontenery Postgres, Redis i Vault za pomocą testcontainers (wymagany Docker).

4. Uruchom aplikację

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

Stos obejmuje aplikację (port 18000), PostgreSQL z pgvector (trzy bazy danych: relacyjna, wektorowa i checkpointy LangGraph), Redis do aktualizacji statusu przez pub/sub oraz Vault do przechowywania sekretów. Interaktywna dokumentacja OpenAPI jest dostępna pod adresem http://localhost:18000/docs.

Uwierzytelnianie jest w szkielecie wyłączone (auth.enabled: false). Gdy je włączysz, każde żądanie będzie wymagać tokenu bearer — zobacz Uwierzytelnianie z Keycloak.

5. Porozmawiaj z agentem przez REST

Agenci są instancjami implementacji, tworzonymi i konfigurowanymi przez API. Utwórz jedną:

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

Skopiuj id z odpowiedzi, a następnie wyślij wiadomość:

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

Odpowiedź wraca synchronicznie:

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

Ta wymiana przeszła przez cały stos: żądanie REST → wyszukanie w rejestrze → kontener DI → twój agent → utrwalenie wiadomości (odpowiedź także zostaje zapisana — sprawdź POST /messages/list). Pełny katalog znajdziesz w Dokumentacji REST API.

6. Obejrzyj ślad

Obserwowalność w Agent-Lab to po prostu OpenTelemetry. Gdy ustawiona jest zmienna środowiskowa OTEL_EXPORTER_OTLP_ENDPOINT, aplikacja eksportuje ślady, metryki i logi OTLP; gdy nie jest ustawiona, śledzenie jest po prostu wyłączone — w żadnym z tych przypadków nie trzeba zmieniać kodu.

Uruchom dołączony do frameworka stos Grafana (z repozytorium frameworka) i skieruj swoją aplikację na jego kolektor:

# 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

Wyślij kolejną wiadomość, a następnie otwórz Grafana pod adresem http://localhost:3000 (admin/admin) i przejrzyj dashboard Agent-Lab: span HTTP, zapytania SQL oraz — w przypadku agentów opartych na LLM — każde wywołanie modelu wraz z liczbą tokenów. Wolisz hostowaną platformę obserwowalności LLM? Ustaw zamiast tego LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY (lub LANGWATCH_ENDPOINT/ LANGWATCH_API_KEY) — szczegóły znajdziesz w Przewodniku po obserwowalności.

7. Spotkaj agenta w kliencie MCP

Szkielet zawiera już narzędzie MCP (my_agent_app/mcp/tools.py) udostępnione pod /mcp, obok frameworkowych narzędzi do wykrywania agentów, historii i wysyłania wiadomości. Wypróbuj je w MCP Inspector:

npx @modelcontextprotocol/inspector

Połącz się z http://localhost:18000/mcp (Streamable HTTP), wyświetl listę narzędzi i wywołaj my_agent_app_hello_tool. Ten sam serwer działa z Claude Desktop i każdym innym klientem MCP — zobacz Przewodnik po serwerze MCP.

Co dalej?