agent threads: thread messages and grant, agent-db service to gRPC by theomonnom · Pull Request #1841 · livekit/protocol

theomonnom · 2026-10-08T00:03:26Z

agent/livekit_agent_thread.proto, one file:
- AgentThread: a thread (AT_) with scope, attributes, idle TTL and the database created with it; create, get, list, update, delete; items as ChatContext.ChatItem, oldest first
- AgentTask: background work an agent runs in a thread (name, status: running, completed, failed, canceled); all of a thread's, optionally by status
livekit/agent/thread_schema_v1.sql (embedded as agent.ThreadSchemaV1): the conversation tables the agents framework writes and the platform reads
auth.AgentThreadGrant (agentThread claim): scope, threadIds, all, list/create/write/read/delete; CanCreate(scope) and CanList(scope) by scope, CanRead, CanWrite, CanDelete(threadID) by id (e.g. a frontend rendering one conversation); all extends it to every thread of the project with the action flags still applying, and CanUpdate() needs it
guid prefixes AT_ (thread) and AST_ (agent stream)
AgentDBService Twirp removed (served as gRPC from cloud-protocol); AgentDB.CreateRequest.region removed; DumpRequest/DumpResponse renamed ExportRequest/ExportResponse; times are Timestamp / Duration
AgentDB batches answer per statement: statement index on Columns, ColumnBatch and ExecResult

AgentThread messages for the durable conversation an agent has with a person, AgentThreadGrant under the agentThread claim, and the AT_ and AST_ id prefixes. The agent-db and thread services are internal gRPC in cloud-protocol, so the AgentDBService Twirp service is removed. A database lives in its project's data region: AgentDB.CreateRequest.region is reserved.

changeset-bot · 2026-10-08T00:03:33Z

🦋 Changeset detected

Latest commit: 18e535d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
github.com/livekit/protocol	Minor
@livekit/protocol	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Keys stay readable in logs, which is what debugging a lookup needs.

…otos

One agent can expose several endpoints (sms, chat, voice). Endpoints names the ones the holder may call; empty allows all. Threads stay per agent, so every endpoint continues the same thread.

davidzhao · 2026-10-08T02:48:39Z

+// endpoints the holder may call; empty allows all of them.
+type AgentThreadGrant struct {
+	AgentName string   `json:"agentName"`
+	Sub       string   `json:"sub,omitempty"`


is this Subject? or Subscription?

It’s Subject, the idea is that you can “group” some threads based on whatever key you want.
This is just there for very simple use cases like: list all the threads from my user (and in this case user is in sub)

Will rename to Subject

should this be a user identity or some sort? since we use identity in RTC land

Yeah i can use Identity, but the thing is that it isn’t necessarily a “Human” ?

It’s also used in the scope. You can give a JWT token to the client side. With this Subject. And it can read/list the threads.

But I expect most ppl to write their own backend when their usecase becomes more advanced

davidzhao · 2026-10-08T02:49:23Z

+// or by id, with per-action flags. Endpoints limits which of the agent's
+// endpoints the holder may call; empty allows all of them.
+type AgentThreadGrant struct {
+	AgentName string   `json:"agentName"`


should this be here? is a thread a piece of data? or is it tied to a specific agent?

it's worth keeping in mind that I may have two separate agents that is capable of picking up the same convo.

Good question, so you can have multiple agents picking up the same conversation. But they must share the same agent_name.

remember that with text mode, an agent is agent_name/{endpoint}

davidzhao · 2026-10-08T02:49:44Z

+	AgentName string   `json:"agentName"`
+	Sub       string   `json:"sub,omitempty"`
+	ThreadIDs []string `json:"threadIds,omitempty"`
+	Endpoints []string `json:"endpoints,omitempty"`


how does this mesh with agentEndpoint grant? what is the relation here?

davidzhao · 2026-10-08T03:02:15Z

+    // When set, create is get-or-create on (agent_name, key).
+    string key = 2;
+    // The subject the thread belongs to, as scoped by an AgentThreadGrant.
+    string sub = 3 [(logger.sensitivity) = SENSITIVITY_PII];


does the end user provide subject? or is it something that we generate? how is this determined?

The end user provide it

davidzhao · 2026-10-08T03:14:03Z

+  message DeleteResponse {}
+
+  // Creates the thread's database if it has none. Idempotent.
+  message EnsureStateDatabaseRequest {


not sure about naming.. maybe

Suggested change

message EnsureStateDatabaseRequest {

message CreateThreadDatabaseRequest {

davidzhao · 2026-10-08T03:14:29Z

+  }
+
+  // Marks a thread as merged into redirect_to.
+  message RedirectRequest {


Suggested change

message RedirectRequest {

message MergeThreadRequest {

davidzhao · 2026-10-08T03:14:49Z

+
+  message Thread {
+    string thread_id = 1 [(logger.name) = "threadID"];
+    string agent_name = 2;


same as earlier comment.. might not want to sticky to agent

davidzhao · 2026-10-08T03:15:19Z

+    map<string, string> attributes = 5 [(logger.sensitivity) = SENSITIVITY_PII];
+    int64 created_at = 6;
+    int64 last_active = 7;
+    int64 expires_at = 8;


how does expires_at play with idle_ttl_seconds?

what is the unit for time?

Will use google.protobuf.Duration/Timestamp

expires_at = last_active + idle_ttl. It's a sliding expiry: every touch or send pushes it out by the idle TTL, and the thread is swept once it passes.

davidzhao · 2026-10-08T03:16:18Z

 message AgentDB {
  message CreateRequest {
-    string region = 1;
+    // A database lives in its project's data region.


…e and MergeThread From review: sub is spelled subject (grant and messages), times are google.protobuf.Timestamp/Duration (threads and the AgentDB lifecycle), EnsureStateDatabase is CreateThreadDatabase, Redirect is MergeThread with merged_into on the thread.

…mble grant uses subject

The thread grant covers thread data only, by scope or id across the project's agents: no agent name and no endpoints, so it never opens a non-public endpoint (agentEndpoint does that). Send is write. The thread's subject is its scope.

davidzhao · 2026-10-08T04:12:39Z

+
+// Allows reports whether a thread is in the grant, by scope or by id. An empty
+// Scope or thread id never matches; the caller checks the flags.
+func (s *AgentThreadGrant) Allows(scope, threadID string) bool {


grant.CanRead(threadID) grant.CanList(scope) grant.CanDelete(threadID) grant.CanWrite(threadID)

One check per action. Per-thread checks take the thread, since a grant matches by scope or by id; create needs only the grant, which creates in its own scope.

A conversation is not owned by one agent: any agent of the project can pick it up. Keys resolve per project, listing is by scope, and GetRequest looks up by thread id or key.

… touch Keys are internal (LiveKit phone numbers): one per thread, set at create. Removes AddKey, RemoveKey, Touch and CreateThreadDatabase; an update counts as activity and the database comes with the thread.

…rotocol into theo/agent-threads-api

…ork state apart; items drop type

…or events.author

…rotocol into theo/agent-threads-api

A Batch answers one result per statement, in order: Columns and ColumnBatch frames for a statement that returns rows, one ExecResult for one that does not, then a single Done for the whole batch. The new statement field on Columns, ColumnBatch and ExecResult is the 0-based index within the batch; a plain Exec or Query leaves it 0. (cherry picked from commit 39517ac)

github-actions Bot and others added 7 commits October 8, 2026 00:04

generated protobuf

3b58124

agent threads: shorter comments, keys are not PII

45962ce

Keys stay readable in logs, which is what debugging a lookup needs.

agent threads: explain AgentThread and AgentDB at the top of their pr…

baf0858

…otos

generated protobuf

7f11c3a

agent threads: tighter proto headers

6961016

generated protobuf

b258754

auth: AgentThreadGrant can limit the agent's endpoints

5e166e4

One agent can expose several endpoints (sms, chat, voice). Endpoints names the ones the holder may call; empty allows all. Threads stay per agent, so every endpoint continues the same thread.

theomonnom mentioned this pull request Oct 8, 2026

agent threads: thread id and grant on jobs and the HTTP preamble #1843

Closed

davidzhao reviewed Oct 8, 2026

View reviewed changes

theomonnom added a commit that referenced this pull request Oct 8, 2026

Merge #1841 (subject, times, CreateThreadDatabase, MergeThread); prea…

e52801b

…mble grant uses subject

github-actions Bot and others added 2 commits October 8, 2026 03:25

generated protobuf

f3a28aa

theomonnom added a commit that referenced this pull request Oct 8, 2026

Merge #1841: the wire grant is scope, ids and flags

d5ad07d

github-actions Bot and others added 2 commits October 8, 2026 04:07

generated protobuf

17ef238

auth: AgentThreadGrant.Allows, like AgentEndpointGrant.Allows

2912148

davidzhao reviewed Oct 8, 2026

View reviewed changes

auth: AgentThreadGrant.CanCreate, CanList, CanRead, CanWrite, CanDelete

5e6b136

One check per action. Per-thread checks take the thread, since a grant matches by scope or by id; create needs only the grant, which creates in its own scope.

davidzhao approved these changes Oct 8, 2026

View reviewed changes

theomonnom and others added 6 commits October 7, 2026 21:23

agent threads: no agent_name; keys and listing are per project

f46c27b

A conversation is not owned by one agent: any agent of the project can pick it up. Keys resolve per project, listing is by scope, and GetRequest looks up by thread id or key.

generated protobuf

7864993

agent threads: one internal key, database created with the thread, no…

2345bef

… touch Keys are internal (LiveKit phone numbers): one per thread, set at create. Removes AddKey, RemoveKey, Touch and CreateThreadDatabase; an update counts as activity and the database comes with the thread.

generated protobuf

c4e191c

agent thread: header matches the single internal key

cc88011

generated protobuf

07d6ab2

theomonnom mentioned this pull request Oct 8, 2026

AgentThread history, tasks and shared conversation schema #1844

Closed

theomonnom and others added 2 commits October 8, 2026 13:24

agent thread: no merge for now

fe85b60

generated protobuf

fb69b0b

theomonnom and others added 26 commits October 8, 2026 14:34

Merge branch 'theo/agent-threads-api' of https://github.com/livekit/p…

e24af55

…rotocol into theo/agent-threads-api

thread schema: tasks keep queried columns, A2A fields in data, framew…

74fdf84

…ork state apart; items drop type

thread schema: say where each table is used

72224f5

thread schema: wrap comments

6e1a630

thread schema: lane is agent, indexes for every query, no applied_at …

c3070f2

…or events.author

thread schema: no task attempts, status says a run was lost

a139187

agent thread: get by id only

44e0aa9

agent thread: no key in the public messages; create returns the thread

5f7279e

generated protobuf

0a02ce5

agent thread: GetItems and GetTasks requests

6de4de2

generated protobuf

e223b92

thread schema: keep the framework's lane naming

dab43d9

thread schema: every column names its reader; tasks.internal; log ids

f624709

agent task: no agent field, no paging

38d1b27

generated protobuf

f965030

agentdb: Export instead of Dump

aca3f2c

generated protobuf

1e517dc

agent: tasks.status values and their AgentTask.Status live here

592b221

agent task: zero status is unspecified, so running shows in JSON

f7ccd2b

generated protobuf

2ad11c8

agent task: status doc

85b4c1c

Merge branch 'theo/agent-threads-api' of https://github.com/livekit/p…

ece8415

…rotocol into theo/agent-threads-api

auth: AgentThreadGrant.All for project-wide thread access

01c6062

changeset: per-statement batch results

089df37

generated protobuf

18e535d

theomonnom merged commit 0740380 into main Oct 9, 2026
5 checks passed

theomonnom deleted the theo/agent-threads-api branch October 9, 2026 20:11

github-actions Bot mentioned this pull request Oct 9, 2026

Version Packages #1820

Open

theomonnom mentioned this pull request Oct 9, 2026

agent threads: items sort order, page tokens like the other lists, items.pos #1851

Open

	message EnsureStateDatabaseRequest {
	message CreateThreadDatabaseRequest {

Conversation

theomonnom commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theomonnom Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

theomonnom commented Oct 8, 2026 •

edited

Loading

changeset-bot Bot commented Oct 8, 2026 •

edited

Loading

theomonnom Oct 8, 2026 •

edited

Loading