智能体数据 (JavaScript)

Agent Data 是一个与 deploymentName 和 collection 绑定的 JSON 存储。使用官方 JavaScript SDK 进行强类型化的增删改查、搜索和聚合操作。

See the Agent Data Overview for concepts, constraints, and environment details.

安装：

npm i -S llama-cloud-services

关键导入项：

import {
  AgentClient,
  createAgentDataClient,
  type TypedAgentData,
  type TypedAgentDataItems,
  type TypedAggregateGroupItems,
  type SearchAgentDataOptions,
  type AggregateAgentDataOptions,
} from "@llama-cloud-services/beta/agent";

创建客户端

该辅助工具在可能的情况下从环境变量或浏览器URL推断deploymentName，默认回退到"_public"。

type Person = { name: string; age: number; email: string };

const client = createAgentDataClient<Person>({
  // Optional: infer agent from env
  env: process.env as Record<string, string>,
  // Optional: infer from browser URL when not localhost
  windowUrl: typeof window !== "undefined" ? window.location.href : undefined,
  // Optional overrides
  // deploymentName: "person-extraction-agent",
  collection: "extracted_people",
});

或者，直接构建一个客户端：

const direct = new AgentClient<Person>({
  // client: default (from SDK) or a custom @hey-api/client-fetch instance
  deploymentName: "person-extraction-agent",
  collection: "extracted_people",
});

浏览器使用情况：

TypeScript SDK 可在浏览器中运行。当您的应用与智能体一同部署在LlamaCloud时，请求将自动完成身份验证。
在其他环境（本地开发、自定义托管）中，为底层客户端提供API密钥。
要将范围限定到特定项目，请在客户端的头部设置 Project-Id。

CRUD 操作

// Create
const created = await client.createItem({ name: "John", age: 30, email: "john@example.com" });

// Get (returns null on 404)
const item = await client.getItem(created.id);

// Update (overwrites data)
const updated = await client.updateItem(created.id, { name: "Jane", age: 31, email: "jane@example.com" });

// Delete
await client.deleteItem(updated.id);

SDK响应是强类型且采用驼峰命名法的。

TypedAgentData<T> 字段：id, deploymentName, collection?, data, createdAt, updatedAt.

按查询删除

删除与筛选条件匹配的多个项目。返回已删除项目的数量。

const deletedCount = await client.delete({
  filter: {
    status: { eq: "inactive" },
    age: { gte: 65 },
  },
});
console.log(deletedCount);

搜索

const options: SearchAgentDataOptions = {
  filter: {
    age: { gte: 21, lt: 65 },
    status: { eq: "active" },
    created_at: { gte: "2024-01-01T00:00:00Z" }, // top-level timestamp
  },
  orderBy: "data.name desc, created_at",
  pageSize: 50,
  offset: 0,
  includeTotal: true, // request on the first page only
};

const results: TypedAgentDataItems<Person> = await client.search(options);
for (const r of results.items) {
  console.log(r.data.name);
}

查看智能体数据概览获取关于筛选器的更多详细信息。

筛选键目标 data 字段，除了 created_at/updated_at 属于顶层字段。
使用逗号分隔的规格进行排序；在orderBy中的数据字段前添加前缀（例如："data.name desc, created_at"）。
默认 pageSize 为 50（最大 1000）。仅在首页使用 includeTotal。

分页：默认页面大小为50（最大1000）。响应可能包含 nextPageToken 和 totalSize。

聚合

const aggOptions: AggregateAgentDataOptions = {
  filter: { status: { eq: "active" } },
  groupBy: ["department", "role"],
  count: true,
  first: true, // earliest by created_at per group
  orderBy: "data.department asc, data.role asc",
  pageSize: 100,
};

const groups: TypedAggregateGroupItems<Person> = await client.aggregate(aggOptions);
for (const g of groups.items) {
  console.log(g.groupKey, g.count, g.firstItem);
}