첫 번째 에이전트

만들게 될 것

완전하고 실행 가능한 Agent-Lab 애플리케이션을 만듭니다. 에코 에이전트, MCP 서버, PostgreSQL 영속성, OpenTelemetry 계측을 갖춘 FastAPI 서비스로, 모두 명령 하나로 스캐폴딩되며 직접 연결할 부분은 없습니다. 그 과정에서 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

스캐폴드는 프레임워크의 포크가 아니라 프레임워크를 사용하는 얇은 소비자입니다. 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",)로 선언하고, 이에 맞는 프로바이더를 core/container.py에 추가하세요(개발자 가이드 참고).

3. 실행 전에 테스트하기

스캐폴드의 단위 테스트는 인프라 없이 애플리케이션 전체를 부팅합니다.

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

통합 테스트도 함께 제공됩니다. make test_integration은 testcontainers를 통해 실제 Postgres, Redis, Vault 컨테이너를 띄웁니다(Docker 필요).

4. 앱 실행

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

스택은 앱(포트 18000), pgvector가 포함된 PostgreSQL(관계형, 벡터, LangGraph 체크포인트의 세 가지 데이터베이스), Pub/Sub 상태 업데이트를 위한 Redis, 시크릿을 위한 Vault로 구성됩니다. 대화형 OpenAPI 문서는 http://localhost:18000/docs에서 확인할 수 있습니다.

스캐폴드에서는 인증이 비활성화되어 있습니다(auth.enabled: false). 인증을 활성화하면 모든 요청에 Bearer 토큰이 필요합니다. 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. 트레이스 확인하기

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

메시지를 하나 더 보낸 다음 http://localhost:3000에서 Grafana를 열고(admin/admin) Agent-Lab 대시보드를 살펴보세요. HTTP 스팬, SQL 쿼리, 그리고 LLM 기반 에이전트의 경우 토큰 수가 포함된 모든 모델 호출을 확인할 수 있습니다. 호스팅형 LLM 관측성 플랫폼을 선호한다면 대신 LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY(또는 LANGWATCH_ENDPOINT/ LANGWATCH_API_KEY)를 설정하세요. 자세한 내용은 관측성 가이드에 있습니다.

7. MCP 클라이언트에서 사용하기

스캐폴드에는 이미 /mcp에 노출된 MCP 도구(my_agent_app/mcp/tools.py)가 포함되어 있으며, 프레임워크의 에이전트 검색, 기록, 메시징 도구도 함께 제공됩니다. MCP Inspector로 사용해 보세요.

npx @modelcontextprotocol/inspector

http://localhost:18000/mcp(Streamable HTTP)에 연결하고, 도구 목록을 조회한 뒤 my_agent_app_hello_tool을 호출하세요. 같은 서버를 Claude Desktop 및 모든 MCP 클라이언트에서 사용할 수 있습니다. MCP 서버 가이드를 참고하세요.

다음 단계