개발자 가이드

Agent-Lab 프레임워크로 애플리케이션을 구축하고, 확장하고, 출시하기

두 가지 개발 방식

Agent-Lab은 라이브러리로 사용하는 프레임워크이면서, 직접 작업할 수 있는 저장소이기도 합니다. 두 방식 모두 지원됩니다.

라이브러리로 사용(제품 개발에 권장). 프로젝트에 btech-agent-lab을 추가하고, 기본 클래스를 확장해 에이전트를 정의한 뒤, create_app()으로 앱을 조립합니다. 프레임워크 코드를 수정하지 않고 상속, 데코레이터, 구성 등 공개 API를 통해 프레임워크를 확장합니다. 튜토리얼 또는 빠른 시작부터 시작한 다음 프레임워크 확장을 읽어 보세요. 보일러플레이트를 건너뛰려면 uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter로 바로 사용할 수 있는 소비자 프로젝트를 스캐폴딩하세요 (cookiecutter/README.md 참고).
저장소 내 개발(기여자 및 레퍼런스 구현용). 저장소를 클론하고 agent_lab/services/agent_types/ 아래에 에이전트를 추가한 뒤, 포함된 레퍼런스 앱을 실행하고 노트북과 통합 테스트를 활용합니다. 기본 제공 에이전트는 이 방식으로 개발됩니다. 에이전트 워크플로 구축을 참고하세요.

두 방식은 같은 구성 요소를 사용하며, 차이는 코드가 어디에 위치하느냐뿐입니다. 프로젝트에 맞는 방식을 선택하세요.

설정

설치

Agent-Lab은 Python 3.12+ 를 대상으로 하며, 의존성 관리에 uv를 사용합니다.

Agent-Lab을 라이브러리로 사용하는 경우 — 프로젝트에 설치하세요.

pip install btech-agent-lab
# or
uv add btech-agent-lab

저장소에서 작업하는 경우 — 저장소를 클론하고 환경을 동기화하세요.

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Docker 또는 다른 컨테이너 런타임이 설치되어 실행 중인지 확인하세요. 통합 테스트는 (testcontainers를 통해) 이를 사용하며, 포함된 Docker Compose 파일이 애플리케이션의 의존성을 제공합니다.

예제 환경 파일 복사

cp .env.example .env

이 파일에는 AI 공급자의 API 키와 에이전트 시뮬레이션에서 사용하는 엔드포인트가 들어 있습니다. 모든 변수는 구성 레퍼런스에 설명되어 있습니다.

레퍼런스 구현

저장소에는 RAG, 브라우저 자동화, 음성 메모, 비전, 멀티 에이전트 supervisor 등 모든 기본 제공 에이전트를 등록하는 완전한 레퍼런스 애플리케이션(agent_lab.main)이 포함되어 있습니다. 이 앱은 배포 가능한 제품이자 프레임워크 사용 방법을 보여 주는 표준 예제입니다. 기본 제공 에이전트 패키지에 대해 create_app()을 호출하는 것이 전부입니다.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

자체 앱을 구축할 때 살아 있는 참고 자료로 활용하고, Agent-Lab을 엔드 투 엔드로 가장 빠르게 체험하는 방법으로 사용하세요. 개발 또는 프로덕션 환경에서 인프라(세 개의 PostgreSQL 데이터베이스, Redis, Keycloak, Vault)를 프로비저닝하는 방법은 배포 가이드에서 다룹니다. 다음 섹션에서는 로컬에서 실행하는 방법을 설명합니다.

애플리케이션 실행

Uvicorn으로 애플리케이션 시작

IDE에서 개발하고 디버깅할 때는 레퍼런스 앱을 직접 실행하세요.

uvicorn agent_lab.main:app --reload

대화형 OpenAPI 문서는 http://localhost:8000/docs에서 확인할 수 있습니다.

Agent-Lab을 라이브러리로 사용하는 경우에도 자체 앱을 같은 방식으로 실행합니다. create_app()을 호출하는 모듈을 uvicorn에 지정하세요.

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Docker Compose로 애플리케이션 시작

사전 구성된 두 개의 Docker Compose 파일이 레퍼런스 앱을 관측성 스택과 함께 실행합니다.

compose-grafana.yml: 애플리케이션과 Grafana, Prometheus, Tempo, Loki.
compose-opensearch.yml: 애플리케이션과 OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

애플리케이션이 시작되면 http://localhost:18000/docs에서 API를 사용할 수 있습니다. 관측성 대시보드:

Grafana: http://localhost:3000 (기본 자격 증명: admin/admin). Grafana 예제를 참고하세요.
OpenSearch Dashboards: http://localhost:5601. OpenSearch 예제를 참고하세요.

개발 관행

의존성 주입

애플리케이션은 의존성 주입에 Dependency Injector를 사용합니다. 이를 통해 관심사를 분리하고 테스트를 쉽게 할 수 있습니다.

컨테이너는 agent_lab/core/container.py에 정의되어 있습니다. Agent-Lab을 라이브러리로 사용할 때는 Container를 상속해 자체 프로바이더를 추가하고, 인스턴스를 create_app(container=...)에 전달하세요. 저장소 내에서 작업할 때는 추가 프레임워크 서비스를 컨테이너에 직접 등록하세요.

애플리케이션 구성

구성은 ConfigSource(agent_lab/core/config.py 참고)를 통해 로드되어 DI 컨테이너에 바인딩됩니다. 프레임워크는 개발 및 테스트용으로 세 가지 YAML 소스를 제공하며, 환경 변수에 따라 자동으로 선택됩니다.

config-dev.yml: 개발 환경. DEVELOPING이 설정되면 활성화되며, IDE 디버깅용입니다.
config-test.yml: 테스트 환경. TESTING이 설정되면 활성화되며, 통합 테스트 설정에서 사용합니다.
config-docker.yml: Docker Compose 환경. DOCKER가 설정되면 활성화됩니다.

이 파일들은 데이터베이스 연결, 인증 등의 설정을 정의하며 개발과 테스트 용도로만 사용합니다. 프로덕션에서는 VaultConfigSource(환경 플래그가 설정되지 않았을 때의 기본값)를 통해 Vault를 사용하세요. 다른 백엔드에서 구성을 제공하려면 자체 ConfigSource를 구현해 create_app(config_source=...)에 전달하세요. 모든 구성 키와 환경 변수는 구성 레퍼런스에 설명되어 있습니다.

엔티티 도메인 모델

애플리케이션 전반에서 사용하는 엔티티와 그 관계, 즉 데이터 모델은 엔티티 도메인 모델을 참고하세요.

로깅 및 관측성

애플리케이션은 로깅과 관측성에 OpenTelemetry를 사용하며, 설정은 agent_lab/infrastructure/metrics/tracer.py에 있습니다. FastAPI, HTTPX, LangChain, SQLAlchemy, OpenAI 호출이 기본적으로 계측되며, Langfuse와 LangWatch용 백엔드를 플러그인 방식으로 연결할 수 있습니다. 자세한 내용은 관측성 가이드를 참고하세요.

테스트

프로젝트는 통합 테스트에 중점을 둔 pytest를 사용하며(커버리지 기준: 90%), Testcontainers를 기반으로 Docker 컨테이너의 실제 서비스를 대상으로 테스트를 실행합니다. 별도의 시뮬레이션 스위트는 LLM-as-judge로 에이전트 동작을 엔드 투 엔드로 평가합니다.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

처음 실행할 때는 Docker 이미지와 임베딩 모델을 다운로드하므로 몇 분 정도 걸릴 수 있습니다. 전체 내용은 테스트 가이드를 참고하세요.

pre-commit 초기화

코드베이스에 기여하거나 Agent-Lab 위에 새 에이전트를 구축할 계획이라면 pre-commit 훅을 설치하세요.

pre-commit install

이렇게 하면 커밋하기 전에 코드가 프로젝트의 코딩 표준을 따르는지 확인할 수 있습니다.

에이전트 워크플로 구축

Agent-Lab은 LLM을 사용해 에이전트 워크플로를 구축하는 강력한 방법을 제공하는 LangGraph를 기반으로 합니다. 모듈식 아키텍처와 에이전트 기본 클래스 덕분에 워크플로를 간단하게 구축할 수 있습니다.

새 에이전트 구현 정의

에이전트는 Agent-Lab의 핵심 개념으로, 작업을 수행하고, 의사 결정을 내리고, 다른 에이전트나 외부 시스템과 상호작용할 수 있는 자율적인 개체를 나타냅니다. 에이전트는 다음 기본 클래스 중 하나의 구체적인 구현입니다.

Agent-Lab 기본 클래스

WorkflowAgentBase를 확장하는 클래스는 다음을 정의합니다.

에이전트의 동작(작업, 의사 결정, 다른 에이전트나 외부 시스템과의 상호작용)을 나타내는 워크플로.
에이전트 동작을 사용자 정의하는 프롬프트(Jinja2 템플릿) 및 기타 설정(벡터 저장소 컬렉션, temperature 등)과 같은 초기화 파라미터.

다음은 음성 전사 및 분석을 수행하는 에이전트를 생성해 데이터베이스에 저장한 후, 영속화된 초기화 파라미터의 예시입니다.

에이전트 초기화 파라미터

동일한 구현을 기반으로 하는 여러 에이전트를 REST API를 통해 생성하고 다듬을 수 있습니다.

`@discoverable_agent`로 에이전트 등록

AgentBase 하위 클래스에 @discoverable_agent("<agent_type>")를 데코레이트하세요. 에이전트 등록에 필요한 것은 이 데코레이터 하나뿐이며, 이를 통해 에이전트는 다음과 같이 됩니다.

에이전트 레지스트리(agent_lab/services/agent_types/registry.py)에서 검색 가능,
DI 컨테이너를 통해 해석 가능(컨테이너가 지연 인스턴스화하고 선언된 extra_deps를 주입),
에이전트 생성 스키마가 agent_type을 레지스트리 기준으로 동적으로 검증하므로 API에서 유효.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

참고(마이그레이션): 이전 버전에서는 각 에이전트를 container.py에 수동으로 연결하고, registry.py에 추가하고, agents/schema.py의 Pydantic 스키마를 확장해야 했습니다. 이 단계들은 이제 더 이상 필요하지 않으며, @discoverable_agent가 모두 처리합니다. 선언한 extra_deps는 인스턴스화 시점에 (상속되었을 수 있는) 컨테이너에서 이름으로 해석됩니다.

에이전트에 AgentUtils 외의 협력 객체가 필요하다면, 컨테이너에 프로바이더로 노출하고 (라이브러리를 사용할 때는 Container 상속) extra_deps에 그 이름을 지정하세요.

에이전트를 검색 가능하게 만들기

프레임워크는 알려 준 에이전트 모듈만 임포트하므로, 데코레이터가 실행되도록 하려면 다음과 같이 합니다.

저장소 내: 에이전트를 agent_lab/services/agent_types/ 아래에 두세요. 레퍼런스 앱은 DEFAULT_SCAN_PACKAGES(create_app())의 일부로 이 패키지를 스캔합니다.
라이브러리로 사용: 패키지를 create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"])에 전달하세요. 명시적인 목록은 기본값을 대체합니다(기본 제공 기능을 제외하는 방법이기도 합니다). 또는 설치된 패키지에서 agent_lab.agents 엔트리 포인트 그룹을 통해 게시하면 소비자가 자동으로 가져갑니다.
```
# pyproject.toml of the package that ships the agents
[project.entry-points."agent_lab.agents"]
my_agents = "my_agents"
```

에이전트 구현 실험하기

동일한 의존성 주입 메커니즘을 사용해 Jupyter에서 에이전트를 대화형으로 테스트하는 예제는 노트북을 참고하세요. 통제된 환경에서 동작을 프로토타이핑하고 검증하기에 편리한 방법입니다. 연구자 가이드를 참고하세요.

REST API 에이전트 인터페이스

에이전트가 등록되면 REST API를 통해 인스턴스를 생성하고 관리할 수 있습니다. 동일한 구현으로 각자 고유한 프롬프트와 설정을 가진 여러 인스턴스를 실행할 수 있습니다. 엔드포인트 카탈로그와 요청 예제는 REST API 레퍼런스를 참고하세요.

에이전트 테스트

통합 테스트(tests/integration/)는 pytest와 testcontainers로 실제 인프라를 대상으로 에이전트를 검증합니다.
시뮬레이션(tests/simulation/)은 LLM-as-judge로 동작을 엔드 투 엔드로 평가합니다. 테스트 가이드를 참고하세요.

MCP 서버

에이전트(및 추가 도구)를 Claude Desktop 같은 MCP 클라이언트에 노출해 에이전트 검색, 대화 기록, 에이전트 간 통신을 지원하는 방법은 MCP 서버 가이드를 참고하세요.

프레임워크 확장

Agent-Lab을 라이브러리로 사용할 때는 프레임워크 코드를 수정하지 않고, 오직 create_app()과 최상위 agent_lab 패키지에서 export되는 공개 API를 통해 애플리케이션을 구성합니다.

확장 지점	방법
에이전트	기본 클래스를 상속하고 `@discoverable_agent`로 데코레이트한 뒤, `scan_packages=[...]` 또는 `agent_lab.agents` 엔트리 포인트로 등록합니다.
서비스 및 의존성	`Container`를 상속해 프로바이더를 추가하고 `create_app(container=...)`로 전달합니다.
구성	`ConfigSource`를 구현하거나(또는 `YamlConfigSource` / `VaultConfigSource` 사용) `create_app(config_source=...)`로 전달합니다.
추가 HTTP 라우트	`APIRouter`를 만들어 (인증 정책과 함께) `RouterMount`로 감싸고 `create_app(extra_routers=[...])`로 전달합니다.
MCP 도구 및 프롬프트	`@discoverable_mcp_tool` / `@discoverable_mcp_prompt` / `@discoverable_mcp_registrar`로 데코레이트하고, 에이전트와 동일한 `scan_packages` / 엔트리 포인트 방식으로 등록하며, `create_app(mcp_instructions=[...])`로 MCP 지침 조각을 추가합니다.
트레이싱 백엔드	`TracingBackend`를 상속하고 `Container`에 등록해 스팬을 자체 플랫폼으로 내보냅니다.

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

위의 모든 항목은 agent_lab에서 export됩니다(agent_lab/__init__.py 참고). 이 설정들이 사용하는 구성 키의 전체 목록은 구성 레퍼런스에 있습니다.

기여하기

커뮤니티의 지원에 깊이 감사드립니다. 문제를 발견했거나 개선 제안이 있다면 GitHub Issues 페이지에 이슈를 등록해 알려 주세요.

프로젝트에 기여하려면 다음 단계를 따르세요.

저장소를 포크합니다.
기능 또는 버그 수정을 위한 새 브랜치를 만듭니다.
pre-commit install을 실행해 pre-commit 훅을 활성화하고, 변경한 뒤, 명확하고 간결한 메시지로 커밋합니다.
변경 사항이 pre-commit 훅과 90% 커버리지 기준(make test)을 통과하는지 확인합니다.
포크한 저장소에 변경 사항을 푸시합니다.
원본 저장소의 main 브랜치로 Pull Request(PR)를 생성합니다.

PR을 검토한 후 피드백을 드리겠습니다. 기여와 지원에 감사드립니다!

프로덕션 배포

포함된 Helm 차트와 Terraform 스크립트를 사용해 레퍼런스 애플리케이션을 프로덕션에 배포하는 방법은 배포 가이드를 참고하세요.