Maxim 통합

Maxim 통합 (Maxim Integration)

Maxim AI는 CrewAI 애플리케이션을 위한 종합적인 에이전트 모니터링, 평가, 옵저버빌리티를 제공해요. Maxim의 한 줄 통합으로 에이전트 상호작용, 성능 메트릭 등을 쉽게 트레이스·분석할 수 있어요.

출처: 문서

본문

Overview (개요)

Maxim AI는 CrewAI 애플리케이션을 위한 종합적인 에이전트 모니터링, 평가, 옵저버빌리티를 제공해요. 한 줄 통합으로 에이전트 상호작용, 성능 메트릭 등을 쉽게 트레이스·분석할 수 있어요.

Features (기능)

Prompt Management (프롬프트 관리)

Maxim의 Prompt Management 기능으로 CrewAI 에이전트용 프롬프트를 생성·조직·최적화할 수 있어요. 지시를 하드코딩하는 대신 Maxim의 SDK를 활용해 버전 관리되는 프롬프트를 동적으로 검색·적용하세요.

Prompt Playground — 플레이그라운드를 통해 프롬프트를 만들고, 다듬고, 실험하고, 배포하세요.
Prompt Versions — 폴더와 버전으로 프롬프트를 조직하고, 툴과 컨텍스트를 연결해 실제 사례로 실험하며, 커스텀 로직으로 배포하세요.
Prompt Comparisons — 모델을 구성하고 프롬프트 플레이그라운드 상단의 드롭다운에서 관련 모델을 선택해 여러 모델 간에 쉽게 실험하세요.

팀이 AI 애플리케이션을 만들 때 실험의 큰 부분은 프롬프트 구조를 반복하는 거예요. 효과적으로 협업하고 변경 사항을 명확하게 조직하려면 Maxim이 프롬프트 버전 관리와 버전 간 비교 실행을 허용해요. AI 애플리케이션을 발전시키면서 프롬프트를 반복하려면 모델, 프롬프트 구조 등에 걸친 실험이 필요해요. 버전을 비교하고 변경에 대해 정보에 입각한 결정을 내리기 위해 비교 플레이그라운드는 결과의 나란히 보기(side by side)를 제공해요.

왜 프롬프트 비교(Prompt comparison)를 사용하나요?

프롬프트 비교는 여러 개별 프롬프트를 하나의 뷰로 결합해 다양한 워크플로우를 위한 간소화된 접근을 가능하게 해요:

모델 비교(Model comparison) — 같은 프롬프트에서 서로 다른 모델의 성능 평가.
프롬프트 최적화(Prompt optimization) — 프롬프트의 서로 다른 버전을 비교해 가장 효과적인 표현 식별.
크로스 모델 일관성(Cross-Model consistency) — 같은 프롬프트에 대해 다양한 모델에서 일관된 출력 보장.
성능 벤치마킹(Performance benchmarking) — 다양한 모델과 프롬프트 간 지연 시간, 비용, 토큰 수 같은 메트릭 분석.

Observability & Evals (옵저버빌리티 & 평가)

Maxim AI는 CrewAI 에이전트를 위한 종합적인 옵저버빌리티·평가를 제공해 각 실행 중 정확히 무엇이 일어나는지 이해하게 도와줘요.

Agent Tracing — 툴 호출, 에이전트 궤적, 의사결정 흐름을 포함해 에이전트의 전체 라이프사이클을 쉽게 추적하세요.
Analytics + Evals — 전체 트레이스 또는 개별 노드에 대한 상세 평가 실행:
- 다단계 상호작용과 세밀한 트레이스 분석
- 세션 레벨 평가(Session Level Evaluations)
- 실제 테스트를 위한 시뮬레이션(Simulations)
Auto Evals on Logs — 필터와 샘플링에 기반해 UI에서 캡처된 로그를 자동으로 평가하세요.
Human Evals on Logs — 인간 평가나 평점으로 로그 품질을 평가하세요.
Node Level Evals — 트레이스나 로그의 어떤 컴포넌트든 평가해 에이전트 동작에 대한 통찰을 얻으세요.
Alerting — error, cost, 토큰 사용량, 사용자 피드백, latency에 임계값을 설정하고 Slack이나 PagerDuty로 실시간 알림을 받으세요.
Dashboards — 시간 경과에 따른 트레이스, 사용량 메트릭, 지연 시간, 에러율을 쉽게 시각화하세요.

Getting Started (시작하기)

Prerequisites (사전 준비)

Python 버전 >=3.10
Maxim 계정 (여기에서 가입)
Maxim API Key 생성
CrewAI 프로젝트

Installation

pip로 Maxim SDK를 설치하세요:

pip install maxim-py

또는 requirements.txt에 추가하세요:

maxim-py

Basic Setup (기본 설정)

1. 환경 변수 설정

### Environment Variables Setup

# Create a `.env` file in your project root:

# Maxim API Configuration
MAXIM_API_KEY=your_api_key_here
MAXIM_LOG_REPO_ID=your_repo_id_here

2. 필수 패키지 임포트

from crewai import Agent, Task, Crew, Process
from maxim import Maxim
from maxim.logger.crewai import instrument_crewai

3. API key로 Maxim 초기화

# Instrument CrewAI with just one line
instrument_crewai(Maxim().logger())

4. 평소처럼 CrewAI 애플리케이션 생성·실행

# Create your agent
researcher = Agent(
    role='Senior Research Analyst',
    goal='Uncover cutting-edge developments in AI',
    backstory="You are an expert researcher at a tech think tank...",
    verbose=True,
    llm=llm
)

# Define the task
research_task = Task(
    description="Research the latest AI advancements...",
    expected_output="",
    agent=researcher
)

# Configure and run the crew
crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True
)

try:
    result = crew.kickoff()
finally:
    maxim.cleanup()  # Ensure cleanup happens even if errors occur

이게 전부예요! 모든 CrewAI 에이전트 상호작용이 로깅되어 Maxim 대시보드에서 볼 수 있어요. 빠른 참조는 Google Colab Notebook을 확인하세요.

Viewing Your Traces (트레이스 보기)

CrewAI 애플리케이션을 실행한 후:

Maxim 대시보드에 로그인.
저장소(repository)로 이동.
에이전트 대화, 툴 사용 패턴, 성능 메트릭, 비용 분석을 포함한 상세 에이전트 트레이스 보기.

Troubleshooting (문제 해결)

Common Issues (일반적인 이슈)

트레이스가 나타나지 않는 경우 — API key와 저장소 ID가 올바른지 확인.
crew를 실행하기 전에 instrument_crewai()를 호출했는지 확인. 이는 로깅 훅을 올바르게 초기화해요.
instrument_crewai() 호출에 debug=True를 설정해 내부 에러를 표면화하세요: instrument_crewai(logger, debug = True)
상세 로그를 캡처하려면 에이전트를 verbose=True로 구성하세요: agent = CrewAgent( ..., verbose = True )
instrument_crewai()가 에이전트를 생성·실행하기 전에 호출되었는지 다시 확인하세요. 당연해 보이지만 흔한 실수예요.

Resources (리소스)

CrewAI Docs — 공식 CrewAI 문서.
Maxim Docs — 공식 Maxim 문서.
Maxim Github — Maxim Github.

더 알아보기 (Learn more)

CrewAI 관측성 개요