gRPC Contracts

The agent runtime exposes two gRPC services on each workspace pod. The orchestrator is the only client — user traffic never reaches the runtime directly.

AgentRuntime Service

Bidirectional streaming service for multi-turn agent conversations.

Converse RPC

rpc Converse(stream ConverseRequest) returns (stream ConverseEvent);

The orchestrator opens a bidi stream. Each ConverseRequest sends a user message; the runtime responds with a sequence of ConverseEvent messages ending with a DoneEvent.

ConverseRequest

Field	Type	Required	Description
session_id	string	Yes	Conversation correlation ID
message	string	Yes	User message text
agent_id	string	No	Target a specific agent (empty = Manager routes)
system_prompt	string	No	One-shot system prompt override
workspace_id	string	First request	Workspace identifier (reused from first request)
user_id	string	First request	Platform user identifier

ConverseEvent

A streaming event from the runtime. Exactly one variant is set per event.

Variant	When	Fields
ChunkEvent	Partial text delta from agent	agent_id, text
ThinkingEvent	Reasoning step (extended thinking)	agent_id, text
ToolCallEvent	Tool invocation starting	agent_id, tool, args_json, call_id
ToolResultEvent	Tool invocation completed	call_id, result_json, error, error_message
DoneEvent	Turn complete (terminal)	model, turns[]
UsageEvent	LLM token usage per call	agent_id, model, prompt_tokens, completion_tokens, total_tokens, tool_use_prompt_tokens, thoughts_tokens, cached_tokens, call_sequence

Event ordering

The server emits zero or more ChunkEvent/ThinkingEvent/ToolCallEvent/ToolResultEvent events, followed by exactly one DoneEvent per input request. Multiple UsageEvents may be emitted per turn (one per LLM round-trip when tool calls happen).

DoneEvent Detail

Field	Type	Description
model	string	LLM model used for this turn
turns	Turn[]	Array of agent contributions

Turn

Field	Type	Description
agent_id	string	Which agent produced this turn
text	string	The agent's response text

---

Memory Service

CRUD operations on workspace memory entries. This is a convenience facade — the actual data lives in the orchestrator's PostgreSQL database.

RPCs

RPC	Description
ListMemories	Query entries with optional category filter and pagination
CreateMemory	Create or upsert a memory entry by key
DeleteMemory	Delete an entry by key

MemoryEntry

Field	Type	Description
key	string	Stable identifier within (workspace, category)
content	string	Memory body text
category	string	Partition for grouping (e.g., "core", "daily", "conversation")
created_at	Timestamp	Creation time
updated_at	Timestamp	Last update time

ListMemoriesRequest

Field	Type	Description
workspace_id	string	Required — workspace scope
category	string	Optional filter (empty = all)
limit	int32	Max entries (0 = server default 100)
offset	int32	Pagination offset

CreateMemoryRequest

Field	Type	Description
workspace_id	string	Required
key	string	Memory key (upserts if exists)
content	string	Memory body
category	string	Category tag

DeleteMemoryRequest

Field	Type	Description
workspace_id	string	Required
key	string	Key to delete

---

Authentication

Both services use the same HMAC bearer token in gRPC metadata:

• Header: authorization: Bearer <token>
• Token format: Base64URL-encoded payload + HMAC-SHA256 signature
• Payload: Encodes user ID and workspace ID
• Validation: Constant-time signature comparison on every RPC

---

Wire Rules

• Bidi stream on an internal cluster port inside each workspace pod
• Session correlation via session_id field, not a header
• No field renumbers or deletions — proto evolution rules apply from day 1
• Proto package: crawbl.agentruntime.v1

---

What's next: See the WebSocket Events for real-time client events, or the REST Endpoints for the HTTP API.