CrewAI Fingerprinting

CrewAI Fingerprinting (핑거프린팅)

각각의 Agent·Crew·Task가 누구인지, 언제 만들어졌는지, 어떤 메타데이터를 갖는지 추적하려면 고유 식별자가 필요해요. CrewAI의 핑거프린팅 시스템은 모든 컴포넌트가 생성될 때 자동으로 고유한 핑거프린트를 부여해서, 감사·추적·컴포넌트 정체성 보존을 가능하게 해 줍니다. 이 핑거프린트는 수동으로 덮어쓸 수 없어요.

출처: 공식문서

본문

핑거프린트란

핑거프린트는 crewai.security 모듈의 Fingerprint 클래스 인스턴스입니다. 각 핑거프린트는 다음을 포함해요.

  • UUID 문자열: 컴포넌트의 고유 식별자. 자동 생성되며 수동 설정 불가
  • 생성 타임스탬프: 핑거프린트가 생성된 시각. 자동 설정되며 수동 수정 불가
  • 메타데이터: 커스터마이징 가능한 추가 정보 딕셔너리

핑거프린트는 컴포넌트 생성 시 자동 생성·할당되고, 각 컴포넌트는 읽기 전용 속성으로 핑거프린트를 노출합니다.

핑거프린트의 용도:

  • 컴포넌트 사용 감사·추적
  • 컴포넌트 정체성 무결성 보장
  • 컴포넌트에 메타데이터 부착
  • 추적 가능한 작업 체인 생성

기본 사용

핑거프린트 접근

from crewai import Agent, Crew, Task

# Create components - fingerprints are automatically generated
agent = Agent(
    role="Data Scientist",
    goal="Analyze data",
    backstory="Expert in data analysis"
)

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

task = Task(
    description="Analyze customer data",
    expected_output="Insights from data analysis",
    agent=agent
)

# Access the fingerprints
agent_fingerprint = agent.fingerprint
crew_fingerprint = crew.fingerprint
task_fingerprint = task.fingerprint

# Print the UUID strings
print(f"Agent fingerprint: {agent_fingerprint.uuid_str}")
print(f"Crew fingerprint: {crew_fingerprint.uuid_str}")
print(f"Task fingerprint: {task_fingerprint.uuid_str}")

핑거프린트 메타데이터 다루기

추가 컨텍스트를 위해 핑거프린트에 메타데이터를 넣을 수 있습니다.

# Add metadata to the agent's fingerprint
agent.security_config.fingerprint.metadata = {
    "version": "1.0",
    "department": "Data Science",
    "project": "Customer Analysis"
}

# Access the metadata
print(f"Agent metadata: {agent.fingerprint.metadata}")

핑거프린트 영속성

핑거프린트는 컴포넌트 수명주기 전반에 걸쳐 지속되고 변하지 않도록 설계되었습니다. 컴포넌트를 수정해도 핑거프린트는 동일하게 유지돼요.

original_fingerprint = agent.fingerprint.uuid_str

# Modify the agent
agent.goal = "New goal for analysis"

# The fingerprint remains unchanged
assert agent.fingerprint.uuid_str == original_fingerprint

결정적 핑거프린트

UUID와 생성 타임스탬프는 직접 설정할 수 없지만, generate 메서드에 시드를 넣어 결정적 핑거프린트를 만들 수 있습니다.

from crewai.security import Fingerprint

# Create a deterministic fingerprint using a seed string
deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id")

# The same seed always produces the same fingerprint
same_fingerprint = Fingerprint.generate(seed="my-agent-id")
assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str

# You can also set metadata
custom_fingerprint = Fingerprint.generate(
    seed="my-agent-id",
    metadata={"version": "1.0"}
)

같은 시드는 항상 같은 핑거프린트를 만들어 내므로, 특정 에이전트·컴포넌트에 안정적인 식별자가 필요할 때 유용합니다.

핑거프린트 구조

from crewai.security import Fingerprint

fingerprint = agent.fingerprint

# UUID string - the unique identifier (auto-generated)
uuid_str = fingerprint.uuid_str  # e.g., "123e4567-e89b-12d3-a456-426614174000"

# Creation timestamp (auto-generated)
created_at = fingerprint.created_at  # A datetime object

# Metadata - for additional information (can be customized)
metadata = fingerprint.metadata  # A dictionary, defaults to {}

더 알아보기