指纹

了解如何使用 CrewAI 的指纹系统，在组件的整个生命周期中对其进行唯一标识和追踪。

概述

CrewAI 中的指纹提供了一种在组件整个生命周期内对其进行唯一标识和追踪的方式。每个 Agent、Crew 和 Task 在创建时都会自动获得一个唯一指纹，且该指纹不能被手动覆盖。

这些指纹可用于：

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

指纹如何工作

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

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

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

基础用法

访问指纹

  1. from crewai import Agent, Crew, Task
  3. # Create components - fingerprints are automatically generated
  4. agent = Agent(
  5.     role="Data Scientist",
  6.     goal="Analyze data",
  7.     backstory="Expert in data analysis"
  8. )
  10. crew = Crew(
  11.     agents=[agent],
  12.     tasks=[]
  13. )
  15. task = Task(
  16.     description="Analyze customer data",
  17.     expected_output="Insights from data analysis",
  18.     agent=agent
  19. )
  21. # Access the fingerprints
  22. agent_fingerprint = agent.fingerprint
  23. crew_fingerprint = crew.fingerprint
  24. task_fingerprint = task.fingerprint
  26. # Print the UUID strings
  27. print(f"Agent fingerprint: {agent_fingerprint.uuid_str}")
  28. print(f"Crew fingerprint: {crew_fingerprint.uuid_str}")
  29. print(f"Task fingerprint: {task_fingerprint.uuid_str}")

使用指纹元数据

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

  1. # Add metadata to the agent's fingerprint
  2. agent.security_config.fingerprint.metadata = {
  3.     "version": "1.0",
  4.     "department": "Data Science",
  5.     "project": "Customer Analysis"
  6. }
  8. # Access the metadata
  9. print(f"Agent metadata: {agent.fingerprint.metadata}")

指纹持久性

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

  1. original_fingerprint = agent.fingerprint.uuid_str
  3. # Modify the agent
  4. agent.goal = "New goal for analysis"
  6. # The fingerprint remains unchanged
  7. assert agent.fingerprint.uuid_str == original_fingerprint

确定性指纹

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

  1. from crewai.security import Fingerprint
  3. # Create a deterministic fingerprint using a seed string
  4. deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id")
  6. # The same seed always produces the same fingerprint
  7. same_fingerprint = Fingerprint.generate(seed="my-agent-id")
  8. assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str
  10. # You can also set metadata
  11. custom_fingerprint = Fingerprint.generate(
  12.     seed="my-agent-id",
  13.     metadata={"version": "1.0"}
  14. )

高级用法

指纹结构

每个指纹具有以下结构：

  1. from crewai.security import Fingerprint
  3. fingerprint = agent.fingerprint
  5. # UUID string - the unique identifier (auto-generated)
  6. uuid_str = fingerprint.uuid_str  # e.g., "123e4567-e89b-12d3-a456-426614174000"
  8. # Creation timestamp (auto-generated)
  9. created_at = fingerprint.created_at  # A datetime object
  11. # Metadata - for additional information (can be customized)
  12. metadata = fingerprint.metadata  # A dictionary, defaults to {}