연구자 가이드

이 가이드의 대상

Agent-Lab에서 실험을 탐색하고, 재현하고, 확장하려는 AI 연구자와 개발자를 위한 가이드입니다. Python을 작성하고, Jupyter를 사용하며, 실험, 에이전트, 파이프라인 관점에서 생각한다면 금방 익숙해질 것입니다. LLM, RAG, 컨테이너 기초 지식이 있으면 도움이 되지만 필수는 아닙니다.

Agent-Lab은 재사용 가능한 구성 요소(에이전트 유형, 도구, 통합)와 함께 단계별 예제가 담긴 Jupyter 노트북 모음을 제공하므로 빠르게 생산성을 높일 수 있습니다.

빠른 시작 — 예제 실행

요구 사항: Python 3.12+, 동작하는 Jupyter 환경(JupyterLab 또는 Notebook), 그리고 엔드 투 엔드 통합을 위한 로컬 Docker(선택 사항). 저장소를 클론한 위치에서 작업합니다.

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

notebooks/를 열고 01_…부터 시작해 관심 있는 노트북을 차례로 진행하세요.

참고:

• 노트북은 대부분 독립적으로 실행됩니다. 각 노트북의 머리말에 필요한 환경 변수와 외부 서비스(API 키, 엔드포인트)가 명시되어 있습니다.
• 필요한 키는 .env에 둡니다. .env.example을 복사해 값을 채우세요 (구성 레퍼런스 참고).
• 저장소 대신 자체 프로젝트에서 Agent-Lab으로 실험하려면 pip install btech-agent-lab으로 설치한 뒤 create_app()으로 앱을 조립하세요. 개발자 가이드의 프레임워크 확장을 참고하세요.

프로젝트 구조 — 간단히 둘러보기

• notebooks/ — 에이전트 유형, 평가, 통합에 대한 대화형 예제입니다. 여기서 시작하세요.
• agent_lab/ — 프레임워크 패키지:
  • app_factory.py — 컴포지션 루트: create_app().
  • core/ — 구성 소스, DI 컨테이너, extra_deps 해석.
  • domain/ — 모델, 리포지토리 인터페이스, 예외(엔티티 도메인 모델).
  • services/ — 비즈니스 로직과 agent_types/ 구현.
  • interface/ — api/(HTTP 라우터)와 mcp/(MCP 서버).
  • infrastructure/ — 데이터베이스, 인증, 메트릭/트레이싱 어댑터.
• tests/ — unit/, integration/, template/, simulation/ 스위트(테스트 및 시뮬레이션 참고).
• doc/ — 지금 읽고 있는 문서.

이 계층을 이해하면 각 동작이 어디에 있는지 알 수 있습니다. 예제는 notebooks에, 핵심 계약은 core/와 domain/에, 어댑터는 infrastructure/에 있습니다.

노트북 — 기본 학습 경로

일반적인 진행 순서:

각 노트북에는 실험 목표에 대한 간단한 설명, 필요한 환경 변수와 시크릿, 헬퍼 함수, 그리고 에이전트의 판단과 메트릭을 살펴볼 수 있는 출력/시각화 결과가 포함되어 있습니다.

팁: 노트북을 순서대로 실행하면 점진적으로 학습할 수 있습니다. 반복 작업 중에는 더 작은 데이터셋과 샘플 크기를 사용해 실행 시간을 짧게 유지하세요.

핵심 개념

• 에이전트 — agent_lab/services/agent_types/ 아래에 등록된 구현 (@discoverable_agent)입니다. 레지스트리는 DI 컨테이너를 통해 이를 지연 해석하며, 선언된 extra_deps를 주입합니다.
• 도구 — 에이전트가 호출할 수 있는 개별 기능(검색, 브라우징, TTS/ASR)으로, agent_lab/infrastructure/ 또는 agent_lab/interface/에 어댑터로 구현됩니다.
• Container — DI 컴포지션 객체(agent_lab/core/container.py)입니다. 실험에 필요한 프로바이더를 추가하려면 이를 상속하세요.
• 리포지토리 — agent_lab/domain/repositories/의 데이터 접근 인터페이스입니다.
• ConfigSource — 구성을 가져오는 출처입니다. 실험에서는 YAML 소스를, 프로덕션에서는 Vault를 사용하세요.

동작을 변경하려면 그 변경이 실험적(노트북만 해당), 아키텍처(core/domain/services), 통합 수준(infrastructure의 어댑터) 중 어디에 해당하는지 먼저 판단하세요. 작고 테스트 가능한 변경을 선호하고, 새로운 동작을 보여 주는 노트북을 추가하거나 업데이트하세요.

실험 실행 및 결과 수집

노트북은 중간 단계를 출력합니다. 더 견고한 실험을 위해서는 다음을 따르세요.

• 무작위성이 중요한 경우 결정적 시드를 사용하세요.

• 연구 질문과 관련된 메트릭(지연 시간, 토큰 사용량, 도구 호출 횟수, 심사 점수)을 수집하세요. 관측성 계층은 모든 데이터를 OpenTelemetry로 내보내며 (관측성 참고), 시뮬레이션 하네스는 심사 점수를 Langfuse/LangWatch에 기록합니다(테스트 및 시뮬레이션 참고).

• 반복 가능한 실행을 위해 노트북 셀을 스크립트로 내보내 CI나 컴퓨팅 노드에서 실행하세요.

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• docker/app/Dockerfile은 재현 가능한 실행을 위해 버전이 고정된 런타임 이미지를 빌드합니다.

새로운 동작 프로토타이핑

1. 새 에이전트 유형 추가: agent_lab/services/agent_types/ 아래에 클래스를 만들고 @discoverable_agent("your_type")로 데코레이트한 뒤, DI 컨테이너를 통해 이를 마운트하고 작은 시나리오로 실행해 보는 노트북을 추가하세요. 전체 과정은 에이전트 워크플로 구축에 있습니다.
2. 임베딩 공급자 교체: agent_lab/infrastructure/ 아래에 호환되는 어댑터를 구현하고 노트북 01로 검증하세요.
3. 검색 저장소 또는 벡터 DB 추가: agent_lab/domain/repositories/에 리포지토리 메서드를, agent_lab/infrastructure/database/에 어댑터를 구현하세요. 작은 로더 노트북으로 데이터를 채우고 쿼리 노트북에서 검색을 시연하세요.

설계 팁: 어댑터 인터페이스는 좁게 유지하고, 작은 단위 테스트로 독립적으로 테스트하세요.

테스트 및 평가

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

핵심 동작을 변경할 때는 단위 테스트와 변경 내용을 보여 주는 짧은 노트북을 함께 추가하세요. 이 조합이 바로 이곳에서 연구를 재현 가능하게 만드는 방법입니다. 전체 하네스, 심사 모델 구성, 평가 플랫폼은 테스트 및 시뮬레이션에서 다룹니다.

재현성 체크리스트

• 환경을 고정하세요(uv + pyproject.toml / uv.lock).
• 시드와 구성 파일(config-dev.yml, config-test.yml)을 기록하세요.
• 노트북 체크포인트와 출력 아티팩트(CSV/JSON)를 실험과 함께 저장하세요.
• 데이터를 내보낸 트레이싱 엔드포인트를 기록해 두세요. 트레이스가 곧 실험 로그입니다.