Agent Data (TypeScript)

Overview

Agent Data is a JSON store tied to an agent_slug and collection. Use the official TypeScript SDK to work with Agent Data in typed fashion, including CRUD, search, and aggregation.

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

Install (workspace example):

pnpm add @llama-cloud-services

Key imports:

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

Create client

The helper infers agentUrlId from env or a window URL when possible, defaulting to _public. You can also pass a pre-configured HTTP client.

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
  // agentUrlId: "person-extraction-agent",
  collection: "extracted_people",
});

Alternatively, construct directly:

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

Browser usage:
- The TS SDK can be used in the browser. When your app is deployed in LlamaCloud alongside your agent, requests are automatically authenticated.
- In other environments (local dev, custom hosting), provide an API key in the underlying client.
- To scope to a specific project, set `Project-Id` on the client’s headers.

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 responses are typed and camel‑cased:

• TypedAgentData<T> fields: id, agentUrlId, collection?, data, createdAt, updatedAt.

Search

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, // ask on first page only
};

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

Filter operators: eq, gt, gte, lt, lte, includes.

• Filter keys target data fields, except created_at/updated_at which are top-level.
• For sorting, prefix data fields with data. (e.g., data.name). Default sort is created_at desc.

Pagination: default page size is 50 (max 1000). The response may include nextPageToken and totalSize.

Aggregate

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);
}

Access control and _public

• Data is scoped to an agent’s project. _public is visible across agents within a project.
• Creating data for a non‑_public agent requires that the agent deployment exists and you have access.

Notes

• Filter keys target data fields; only created_at/updated_at are top-level.
• Sort with comma-separated specs; prefix data fields in orderBy (e.g., "data.name desc, created_at").
• Default pageSize is 50 (max 1000). Prefer includeTotal only on the first page.
• _public is required in local dev; use collections to separate apps. Non-_public requires an existing deployment and access.
• getItem returns null on 404; updateItem overwrites the entire data object.
• SDK responses are camelCase and Date-typed for timestamps.