Wire types

beam_types defines the JSON that crosses process boundaries: API to worker, worker to stream, and client to API. Fields marked optional are left out of the JSON when empty, and empty metadata objects are omitted. The repository's tests/wire_compat fixtures lock these shapes.

InvokeRequest

API → worker, and the body of the invoke_agent task.

{
  "agent_name": "kb-assistant",
  "content": [{"type": "text", "text": "what is riverbeam?"}],
  "session_id": "5f8915eb-31eb-4f8a-9517-e2c15ce7bc41",
  "metadata": {"source": "web"},
  "request_id": "16d12ddc-651a-431d-997c-a756d5793ebf",
  "stream": true
}

Field	Type	Required	Meaning
agent_name	string	yes	Registered agent to run
content	ContentPart[]	yes	The user turn
session_id	UUID	yes	Conversation id; a new id starts a session
model_override	string		Model name to use instead of routing
metadata	object		Free-form; see the keys below
interaction_id	UUID		Required to resume; generated otherwise
request_id	UUID		Required for streaming; names the stream channel
stream	bool		Publish frames (default false)
actions	ActionResponseEnvelope[]		Makes this a resume turn
auth_context	InvokeAuthContext		Who is calling

Metadata keys Riverbeam reads:

Key	Read by	Effect
memory_scopes	Pipeline	[{"name", "id"}] layers to load into the context
capabilities	CapabilityStrategy	Capabilities the model must have
confirm	RigAgentRunner	true skips approval for confirm_required tools
sandbox_root, protected_refs	Sandbox tools with no bound tree	Working directory and protected refs

memory_scopes, confirm, sandbox_root and protected_refs change what a run can read or do. Strip them from client requests and set them in your API when you need them.

The API commands take InvokePayload (no request_id, interaction_id or actions; they are filled in) and ResumePayload (adds the required interaction_id and actions).

InvokeAuthContext

Field	Meaning
user_id	Subject for authorization, usage and audit
profile_id	Stored on the session
org_id	Organization; also accepted as organization_id
mcp_token	Not used by Riverbeam; agents can read it from input.auth_context

ContentPart

{"type": "text", "text": "hello"}

Field	Meaning
type	text, image_url, image_base64, audio, file, video, media_ref, reasoning
text	Text for text and reasoning
url	For image_url and similar
data	Inline (base64) data
mime_type	Decides the modality of file and media_ref parts
media_id	UUID of stored media
metadata	Free-form

Each part has a modality: text, image, audio or video. text and reasoning are text; file and media_ref follow their mime_type prefix (image/, audio/, video/), defaulting to text.

AgentResult

Worker → API. The result of invoke, and the result of the final stream frame.

{
  "content": [{"type": "text", "text": "Echo: what is riverbeam?"}],
  "agent_name": "kb-assistant",
  "model_used": "gpt-4o-mini",
  "session_id": "5f8915eb-31eb-4f8a-9517-e2c15ce7bc41",
  "request_id": "16d12ddc-651a-431d-997c-a756d5793ebf",
  "interaction_id": "40744652-2720-4b10-86ee-7333c1be8165",
  "token_usage": {"prompt_tokens": 4, "completion_tokens": 4, "total_tokens": 8},
  "latency_ms": 0.0,
  "interrupted": false
}

Field	Meaning
content	The reply, as content parts
agent_name, model_used	Who answered, with which model
session_id, request_id, interaction_id	Correlation ids
token_usage	prompt_tokens, completion_tokens, total_tokens
tool_calls	ToolCallRecord[]: tool_name, args, tool_call_id, result, latency_ms
metadata	Free-form
latency_ms	Agent latency
interrupted	true when the agent is waiting for approval
action_required	The approvals it is waiting for; see Human approval

StreamChunk

Worker → stream subscribers.

{
  "type": "done",
  "result": {
    "content": [{"type": "text", "text": "Echo: what is riverbeam?"}],
    "agent_name": "kb-assistant",
    "interrupted": false
  },
  "agent_name": "kb-assistant",
  "session_id": "5f8915eb-31eb-4f8a-9517-e2c15ce7bc41",
  "run_id": "c36c753f-b90d-4834-9112-e12a343f6a0d"
}

Field	Meaning
type	chunk, done, error, placeholder, thinking, tool
data	An AgentMessage for chunk, thinking, placeholder and tool frames
result	The AgentResult, on done
error	The message, on error
agent_name, agent_id, session_id, interaction_id, run_id, step_id, message_id	Correlation ids
id, timestamp	Optional frame id and time

AgentMessage has a role (system, human, ai, tool), a type (message, tool_result, action, action_result, step), content, an id, a timestamp, the correlation ids, tool fields (tool_call_id, tool_name, tool_args, tool_result, tool_calls), is_delta, and a phase (final or thinking).

ActionResponseEnvelope

Client → API, inside actions when resuming.

{
  "action_id": "9c1b2d3e-4f50-4a61-8273-849506172839",
  "kind": "confirmation",
  "request_id": "2b7c4d5e-6f70-4a81-9293-a4b5c6d7e8f9",
  "status": "submitted",
  "payload": {"approved": true},
  "responder_id": "u1",
  "responded_at": "2026-06-09T09:46:01.566411Z"
}

Field	Required	Meaning
action_id	yes	The pending action's UUID, from action_required
kind	yes	The action kind, such as confirmation
request_id	yes	Id of this response
status		submitted (default), cancelled, expired, invalid
payload		The response; RigAgentRunner reads tool and args from it
errors		Validation messages
responder_id		Who answered
responded_at		Defaults to now
lc_action_id		An external action id, passed through

ModelConfig

Used by the router and the model list file.

Field	Default	Meaning
name	required	Unique model name
provider	required	openai, anthropic, custom, ollama, groq, nvidia
modalities	[text]	Input modalities
capabilities	[]	Free-form capability names
cost_per_1k_tokens	0.0	Used to prefer cheaper models
max_tokens	4096	Context budget for memory trimming
api_key	none	Avoid; load keys from the environment
provider_config, extra	null	Free-form JSON