CrewAI 트레이싱

CrewAI 트레이싱 (CrewAI Tracing)

CrewAI 는 크루(Crew)와 플로우(Flow)를 실시간으로 모니터링·디버깅할 수 있는 내장 트레이싱을 제공해요. 에이전트 결정, 태스크 실행 타임라인, 도구 사용, LLM 호출을 CrewAI AMP 플랫폼에서 한눈에 볼 수 있습니다. 이 가이드는 크루와 플로우의 트레이싱을 켜는 방법을 차근차근 안내합니다.

출처: 공식문서

본문

CrewAI 내장 트레이싱이란

CrewAI 의 내장 트레이싱은 에이전트 결정, 태스크 실행 타임라인, 도구 사용, LLM 호출에 대한 포괄적인 관측성을 제공하며, 모두 CrewAI AMP 플랫폼에서 확인할 수 있습니다. 트레이싱은 텔레메트리와 독립적으로 관리됩니다.

사전 요구사항

트레이싱을 쓰려면 다음이 필요합니다.

CrewAI AMP 계정: app.crewai.com 에서 무료 계정 가입
CLI 인증: CrewAI CLI 로 로컬 환경 인증

crewai login

설정 절차

1단계: CrewAI AMP 계정 만들기

app.crewai.com 에 방문해 무료 계정을 만드세요. 트레이스·메트릭을 보고 크루를 관리할 수 있는 CrewAI AMP 플랫폼에 접근할 수 있게 됩니다.

2단계: CrewAI CLI 설치 및 인증

아직 설치하지 않았다면 CLI 도구와 함께 CrewAI 를 설치합니다.

uv add 'crewai[tools]'

그 다음 CLI 를 CrewAI AMP 계정으로 인증합니다.

crewai login

이 명령은 브라우저로 인증 페이지를 열고, 장치 코드(device code) 입력을 요청하며, 로컬 환경을 CrewAI AMP 계정으로 인증하고, 로컬 개발의 트레이싱을 활성화합니다.

3단계: 크루에서 트레이싱 켜기

크루에서 tracing 파라미터를 True 로 설정하면 됩니다.

from crewai import Agent, Crew, Process, Task
from crewai_tools import SerperDevTool

# 에이전트 정의
researcher = Agent(
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in AI and data science",
    backstory="""You work at a leading tech think tank.
    Your expertise lies in identifying emerging trends.
    You have a knack for dissecting complex data and presenting actionable insights.""",
    verbose=True,
    tools=[SerperDevTool()],
)

writer = Agent(
    role="Tech Content Strategist",
    goal="Craft compelling content on tech advancements",
    backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles.
    You transform complex concepts into compelling narratives.""",
    verbose=True,
)

# 태스크 생성
research_task = Task(
    description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024.
    Identify key trends, breakthrough technologies, and potential industry impacts.""",
    expected_output="Full analysis report in bullet points",
    agent=researcher,
)

writing_task = Task(
    description="""Using the insights provided, develop an engaging blog
    post that highlights the most significant AI advancements.
    Your post should be informative yet accessible, catering to a tech-savvy audience.""",
    expected_output="Full blog post of at least 4 paragraphs",
    agent=writer,
)

# 크루에서 트레이싱 활성화
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential,
    tracing=True,  # 내장 트레이싱 활성화
    verbose=True
)

# 크루 실행
result = crew.kickoff()

4단계: 플로우에서 트레이싱 켜기

비슷하게 CrewAI 플로우에서도 트레이싱을 활성화할 수 있습니다.

from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel

class ExampleState(BaseModel):
    counter: int = 0
    message: str = ""

class ExampleFlow(Flow[ExampleState]):
    def __init__(self):
        super().__init__(tracing=True)  # 플로우 트레이싱 활성화

    @start()
    def first_method(self):
        print("Starting the flow")
        self.state.counter = 1
        self.state.message = "Flow started"
        return "continue"

    @listen("continue")
    def second_method(self):
        print("Continuing the flow")
        self.state.counter += 1
        self.state.message = "Flow continued"
        return "finish"

    @listen("finish")
    def final_method(self):
        print("Finishing the flow")
        self.state.counter += 1
        self.state.message = "Flow completed"

# 트레이싱을 켜고 플로우 생성·실행
flow = ExampleFlow(tracing=True)
result = flow.kickoff()

5단계: CrewAI AMP 대시보드에서 트레이스 보기

크루나 플로우를 실행한 뒤 CrewAI AMP 대시보드에서 생성된 트레이스를 확인할 수 있습니다. 에이전트 상호작용, 도구 사용, LLM 호출의 상세 단계가 보입니다. 대시보드의 Trace 탭으로 이동하세요.

대안: 환경 변수 설정

전역으로 트레이싱을 켜려면 환경 변수를 설정할 수도 있습니다.

export CREWAI_TRACING_ENABLED=true

또는 .env 파일에 추가:

CREWAI_TRACING_ENABLED=true

이 환경 변수가 설정되면 tracing=True 를 명시하지 않아도 모든 크루와 플로우에 자동으로 트레이싱이 활성화됩니다.

첫 실행 후 트레이스 보기

크루나 플로우를 처음 실행하면 대화형 터미널이 물어볼 수 있습니다.

Would you like to view your execution traces? [y/N]

yes 를 선택하면 보기 링크가 열립니다. 나중에 crewai traces enable 또는 crewai traces disable 명령으로 바꾸거나, 크루/플로우에서 tracing 을 설정해 변경할 수 있습니다.

트레이스 보기

CrewAI AMP 대시보드 접근

app.crewai.com 에 방문해 계정 로그인
프로젝트 대시보드로 이동
Trace 탭 클릭해 실행 상세 확인

트레이스에서 볼 수 있는 것

에이전트 결정(Agent Decisions): 에이전트가 태스크를 어떻게 추론하고 결정하는지
태스크 실행 타임라인: 태스크 시퀀스와 의존성의 시각적 표현
도구 사용(Tool Usage): 어떤 도구가 호출됐고 결과가 무엇인지
LLM 호출(LLM Calls): 프롬프트·응답을 포함한 모든 언어모델 상호작용 추적
성능 메트릭: 실행 시간, 토큰 사용량, 비용
오류 추적: 상세 오류 정보와 스택 트레이스

CrewAI 트레이싱