指纹

概述

CrewAI 中的指纹提供了一种在组件整个生命周期中唯一标识并跟踪它们的方式。每个 Agent、Crew 和 Task 在创建时都会自动获得一个唯一指纹，且无法手动覆盖。

这些指纹可用于：

• 审计和跟踪组件使用情况
• 确保组件身份完整性
• 为组件附加元数据
• 创建可追踪的操作链

指纹如何工作

指纹是 crewai.security 模块中 Fingerprint 类的一个实例。每个指纹包含：

• UUID 字符串：组件的唯一标识符，自动生成，无法手动设置
• 创建时间戳：指纹生成的时间，自动设置，无法手动修改
• 元数据：可自定义的附加信息字典

组件创建时会自动生成并分配指纹。每个组件都会通过只读属性暴露其指纹。

基本用法

访问指纹

from crewai import Agent, Crew, Task

# 创建组件 - 指纹会自动生成
agent = Agent(
    role="数据科学家",
    goal="分析数据",
    backstory="数据分析专家"
)

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

task = Task(
    description="分析客户数据",
    expected_output="来自数据分析的洞察",
    agent=agent
)

# 访问指纹
agent_fingerprint = agent.fingerprint
crew_fingerprint = crew.fingerprint
task_fingerprint = task.fingerprint

# 打印 UUID 字符串
print(f"Agent fingerprint: {agent_fingerprint.uuid_str}")
print(f"Crew fingerprint: {crew_fingerprint.uuid_str}")
print(f"Task fingerprint: {task_fingerprint.uuid_str}")

使用指纹元数据

你可以为指纹添加元数据，以提供更多上下文：

# 为 agent 的指纹添加元数据
agent.security_config.fingerprint.metadata = {
    "version": "1.0",
    "department": "Data Science",
    "project": "Customer Analysis"
}

# 访问元数据
print(f"Agent metadata: {agent.fingerprint.metadata}")

指纹持久性

指纹被设计为在组件生命周期内保持不变。如果你修改组件，指纹仍然保持相同：

original_fingerprint = agent.fingerprint.uuid_str

# 修改 agent
agent.goal = "新的分析目标"

# 指纹保持不变
assert agent.fingerprint.uuid_str == original_fingerprint

确定性指纹

虽然你不能直接设置 UUID 和创建时间戳，但可以使用带种子的 generate 方法创建确定性指纹：

from crewai.security import Fingerprint

# 使用种子字符串创建确定性指纹
deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id")

# 相同的种子总会生成相同的指纹
same_fingerprint = Fingerprint.generate(seed="my-agent-id")
assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str

# 你也可以设置元数据
custom_fingerprint = Fingerprint.generate(
    seed="my-agent-id",
    metadata={"version": "1.0"}
)

高级用法

指纹结构

每个指纹都具有如下结构：

from crewai.security import Fingerprint

fingerprint = agent.fingerprint

# UUID 字符串 - 唯一标识符（自动生成）
uuid_str = fingerprint.uuid_str  # 例如 "123e4567-e89b-12d3-a456-426614174000"

# 创建时间戳（自动生成）
created_at = fingerprint.created_at  # 一个 datetime 对象

# 元数据 - 附加信息（可自定义）
metadata = fingerprint.metadata  # 一个字典，默认是 {}