注意

LlamaAgents 的云端部署目前处于 beta 预览阶段，已广泛开放以供反馈。你可以在本地试用，或部署到 LlamaCloud 并通过应用内的反馈按钮把意见发给我们。

什么是 Agent Data？

省掉数据库搭建。LlamaAgents 的工作流与 JavaScript 界面共享一个内置于 LlamaCloud API 的持久化 Agent Data 存储。它使用与该 API 其他部分相同的鉴权。

Agent Data 是一个可查询的 JSON 记录存储，存放由你的智能体产出的数据。每条记录都关联到一个 deployment_name（已部署的智能体）以及一个可选的 collection（逻辑分桶，默认为 default）。用它来持久化抽取结果、事件、指标及其他结构化输出，并在记录之间做检索与聚合。

核心概念：

• deployment_name：数据所属智能体部署的标识。访问权限按该智能体所在的项目来授权。
• collection：智能体内部的逻辑命名空间，用于组织不同的数据类型或应用。存储形式是 JSON。建议把同质的数据类型存放在同一个 collection 内。
• data：由你的应用决定形状的 JSON 载荷。各 SDK 提供了带类型的封装。

重要行为与约束：

• 必须有部署：deployment_name 必须对应一个已存在的部署。数据会与那个部署及其项目关联。
• 本地开发：在本地运行时，省略 deployment_name 即可使用共享的 _public Agent Data 存储。本地开发时用不同的 collection 名来隔离各个应用。
• 访问控制：你只能读写你有权访问的项目内智能体的数据。_public 数据在同一项目内的各智能体之间可见。

SDK 参考

关于增删改查、检索、过滤、排序、聚合与删除，见自动生成的 SDK 参考：

Agent Data API 参考

该参考覆盖了所有可用操作：

• Create / Get / Update / Delete 单条记录
• Search：支持过滤、排序与分页
• Aggregate：按字段分组，支持计数与取首条
• Delete by query：用过滤 DSL 做批量删除

SDK 包：

• Python：llama-cloud（pip install 'llama-cloud>=1'）
• JavaScript：@llamaindex/llama-cloud（npm install @llamaindex/llama-cloud）

ExtractedData 封装类型

ExtractedData 是一个专用封装类型，可在 Python SDK（llama-cloud）与 JavaScript 界面库（@llamaindex/ui）中使用。它不属于自动生成的 API 参考，因此在这里说明。

ExtractedData[T] 面向数据要经过复核与审批阶段的抽取类工作流。把抽取结果存入 Agent Data 时，用它作为类型参数。

字段：

字段	说明
original_data	最初抽取到的数据（为变更追踪而保留）
data	数据的当前状态（由人工复核更新）
status	工作流状态：pending_review、accepted、rejected、error，或自定义字符串
overall_confidence	汇总的置信度分数（由 field_metadata 自动计算）
field_metadata	把字段路径映射到元数据的字典，含置信度分数与引用出处
file_id	源文档在 LlamaCloud 中的文件 ID
file_name	源文件名
file_hash	用于去重的内容哈希
metadata	额外的应用自定义元数据

Python 用法：

from pydantic import BaseModel
from llama_cloud.types.beta.extracted_data import ExtractedData

class Invoice(BaseModel):
    vendor: str | None = None
    total: float | None = None
    date: str | None = None

使用 client.beta.agent_data 资源来存储 ExtractedData 记录。数据会以符合 ExtractedData 结构的 JSON 字典序列化。

从抽取任务创建：

from_extract_job 工厂方法可以直接从已完成的 ExtractV2Job 创建一个 ExtractedData 实例，并自动捕获字段元数据（置信度分数、引用出处）：

from llama_cloud.types.beta.extracted_data import ExtractedData

extracted = ExtractedData.from_extract_job(
    job=extract_job,
    schema=Invoice,
)

await client.beta.agent_data.create(
    data=extracted.model_dump(),
    deployment_name=deployment_name,
    collection="invoices",
)

手工创建：

当你要从其他来源构造抽取数据，或要转换成不同的 schema 时，使用 ExtractedData.create：

from llama_cloud.types.beta.extracted_data import ExtractedData

invoice = Invoice(vendor="Acme Corp", total=1500.00, date="2024-01-15")

extracted = ExtractedData.create(
    data=invoice,
    status="pending_review",
    file_id="file-abc123",
    file_name="invoice.pdf",
    file_hash="sha256:...",
    field_metadata={
        "vendor": {"confidence": 0.95, "citation": [{"page": 1, "matching_text": "Acme Corp"}]},
        "total": {"confidence": 0.92},
    },
)

JavaScript / TypeScript 用法：

在 @llamaindex/ui 中，ExtractedData 以 TypeScript 类型提供，用于在界面组件里展示带复核流程的抽取结果。