Crew AI

Crew AI

CrewAI로 만든 자율 AI 에이전트 팀을 한 줄의 코드로 추적·평가하고 싶을 때가 있어요. Confident AI는 init() 한 번으로 CrewAI 크루를 추적합니다. 모든 kickoff가 Observatory에서 crew → task → agent → tool 전체 계층을 가진 트레이스로 나타나서, 어떤 에이전트가 어떤 도구를 불렀고, 각 모델 호출이 뭘 반환했고, 시간과 토큰이 어디로 갔는지 보여줘요.

출처: 문서

본문

개요

CrewAI는 모든 시나리오에 맞춰 자율 AI 에이전트를 만드는 가볍고 매우 빠른 Python 프레임워크입니다. Confident AI는 한 줄의 코드로 CrewAI 크루를 추적·평가할 수 있게 해 줘요 — 모든 kickoff가 Observatory에서 crew → task → agent → tool 전체 계층을 가진 트레이스로 나타나죠. 어떤 에이전트가 어떤 도구를 호출했는지, 각 모델 호출이 무엇을 반환했는지, 시간과 토큰이 어디로 갔는지 볼 수 있어요.

CrewAI 스팬은 실행의 구조 — 크루, 작업, 에이전트, 도구 — 를 나타냅니다. 각 작업 안의 OpenAI(또는 Anthropic, Gemini, Bedrock) 호출은 여전히 LLM 스팬으로, 메시지·모델 이름·토큰 사용량과 함께 나타나요. init()이 CrewAI와 함께 켜는 프로바이더 통합이 포착합니다.

자동 계측

EU 리전 사용자는 OTEL 엔드포인트를 EU 버전으로 설정하세요. 그렇지 않으면 트레이스가 우리 US 서버로 보내집니다.

export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

의존성 설치

confident-trace를 CrewAI 및 크루가 쓰는 모델 프로바이더 SDK와 함께 설치하세요(아래 예는 OpenAI를 사용).

pip install confident-trace crewai openai

Confident AI 키 설정

Confident AI Project API key를 받아 환경 변수로 설정하거나, init()에 직접 전달하세요.

export CONFIDENT_API_KEY="<your-confident-api-key>"
export OPENAI_API_KEY="<your-openai-key>"

from confident_trace import init

init(api_key="<your-confident-api-key>")

CrewAI 구성

시작 시, 어떤 크루든 kickoff 하기 전에 init()을 한 번 호출하세요. crewai에서 Agent, Task, Crew를 평소처럼 가져오면 됩니다 — 설치된 프레임워크는 자동으로 감지돼요.

from confident_trace import init, shutdown
from crewai import Agent, Crew, Task

init()

agent = Agent(
    role="Consultant",
    goal="Write clear, concise explanations.",
    backstory="An expert consultant with a keen eye for software trends.",
    llm="openai/gpt-4o-mini",
)

task = Task(
    description="Explain the given topic",
    expected_output="A clear and concise explanation.",
    agent=agent,
)

crew = Crew(agents=[agent], tasks=[task])

try:
    result = crew.kickoff({"input": "What are LLMs?"})
    print(result.raw)
finally:
    shutdown()

init()은 CrewAI의 실행 경계를 훅합니다 — Crew.kickoff와 그 async 변형, 작업 실행, Agent.execute_task / aexecute_task, Flow.kickoff_async / resume_async와 Flow 메서드, 그리고 도구 run/invoke 메서드요. async 편의 메서드는 그 경계로 위임하므로 중복 스팬은 보이지 않아요.

한 번 초기화하고, 한 번 종료하세요. 장기 실행 서버에서는 시작 시 init()을, 정상 종료 시 활성 크루 작업이 끝난 뒤 shutdown()을 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

CrewAI 실행

스크립트를 실행해 크루를 kickoff 하세요.

python main.py

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스와 자식 스팬을 확인하세요.

트레이스가 안 보이면, 거의 항상 프로그램이 트레이스를 보낼 기회가 생기기 전에 종료됐기 때문이에요. 종료 전에 반드시 shutdown()(장기 실행 프로세스에선 flush())을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

CrewAI 크루와 흐름 실행은 계층이 그대로 보존된 채 내보내져서, kickoff에서 시작해 작업·에이전트·모델 호출·도구를 따라갈 수 있어요.

• 크루·작업·흐름 실행 — 작업 이름, 타이밍, 상태, 단계 사이의 부모-자식 관계
• 에이전트 실행 — 각 에이전트에게 보낸 작업 프롬프트와 에이전트의 최종 답변
• 모델 호출 — 메시지, 모델 상세, 도구 요청, 완료 사유, 토큰 사용량
• 도구 호출 — 도구 이름과 그 입출력
• 커스텀 스팬 — 도구나 흐름 안에서 만든 커스텀 애플리케이션 스팬이 그 아래에 중첩되어 유지

포착되는 입력·출력·메시지는 콘텐츠 정책을 따릅니다. 에이전트 구성, 자격 증명, 메모리 저장소, 체크포인트 상태는 내보내지지 않아요.

모델 스팬은 크루의 LLM이 지원되는 프로바이더 SDK를 거칠 때만 나타나요. 그 SDK를 우회하는 커스텀 LLM 구현이나 LiteLLM 라우트는 크루 구조만 보여주고 LLM 스팬은 없습니다 — 지원되는 프로바이더를 쓰거나, 그 호출을 명시적으로 계측하세요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. crew.kickoff()이 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import init, trace_context

init()

with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    result = crew.kickoff({"input": "Explain OpenTelemetry in one sentence."})

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

CrewAI 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 CrewAI 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

from confident_trace import init, turn

init()

with turn("support-turn", thread_id="chat-42"):
    context = crew.kickoff({"input": "Find the relevant account details."})
    answer = crew.kickoff({"input": f"Summarize these details: {context.raw}"})

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

CrewAI 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. CrewAI의 식별자는 Python에서 "crewai"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

from confident_trace import init
init(instrumentations=())
# Use ("crewai",) to opt in; omit "crewai" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

크루를 추적했으니, 더 깊이 들어가 볼까요.

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 크루 품질을 모니터링하세요.

Threads

같은 대화의 kickoff를 스레드로 묶고, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

• Online Evals — 수집되는 트레이스·스팬을 실시간으로 평가
• Threads — 크루 실행을 스레드로 묶어 평가