Skip to main content
The roz API server exposes a gRPC service multiplexed on the same port as REST (default localhost:8080). gRPC requires HTTP/2. The service is defined in proto/roz/v1/agent.proto. gRPC reflection is enabled, so you can inspect the API with grpcurl: 
grpcurl localhost:8080 list
# roz.v1.AgentService

​
Service Definition

service AgentService {
  // Bidirectional streaming for interactive agent sessions.
  rpc StreamSession(stream SessionRequest) returns (stream SessionResponse);

  // Watch worker lifecycle events for a multi-agent task.
  rpc WatchTeam(WatchTeamRequest) returns (stream TeamEvent);
}

​
Session Protocol

A session is a bidirectional stream. The client sends SessionRequest messages and receives SessionResponse messages. The typical flow is: 
Client                              Server
  │                                    │
  │─── StartSession ──────────────────►│
  │◄── SessionStarted ────────────────│
  │                                    │
  │─── UserMessage ───────────────────►│
  │◄── ThinkingDelta (stream) ────────│
  │◄── TextDelta (stream) ────────────│
  │◄── ToolRequest ───────────────────│
  │─── ToolResult ────────────────────►│
  │◄── TextDelta (stream) ────────────│
  │◄── TurnComplete ─────────────────│
  │                                    │
  │─── CancelSession ────────────────►│
  │                                    │

​
StartSession

Opens a new agent session. The server responds with SessionStarted.
FieldTypeDescription
environment_idstringEnvironment to run in.
host_idstring (optional)Target edge host for OODA mode.
modelstring (optional)LLM model override (e.g. "claude-sonnet-4-20250514").
toolsToolSchema[]Initial set of tools the client provides.
historyConversationMessage[]Previous conversation to resume.
project_contextstring[]Project-specific context blocks (e.g. AGENTS.md content).
max_context_tokensuint32 (optional)Context window budget.

​
SessionStarted

Confirms the session is active.
FieldTypeDescription
session_idstringUnique session identifier.
modelstringThe model being used.
permissionsPermissionRule[]Tool permission policies for this session.

​
UserMessage

Sends a user prompt to the agent.
FieldTypeDescription
contentstringThe user’s message text.
contextContentBlock[]Additional context (text or binary).
ai_modestring (optional)Force a specific agent mode ("react" or "ooda_re_act").
message_idstring (optional)Client-generated ID, echoed in response chunks.
toolsToolSchema[]Full tool snapshot for this turn (replaces session tools if present).
system_contextstring (optional)Per-turn system context injection.

​
TextDelta / ThinkingDelta

Streamed response chunks from the agent. TextDelta contains visible output. ThinkingDelta contains the model’s internal reasoning (when extended thinking is enabled).
FieldTypeDescription
message_idstringMatches the UserMessage.message_id.
contentstringThe text chunk.

​
TurnComplete

Signals that the agent has finished responding to a UserMessage.
FieldTypeDescription
message_idstringMatches the UserMessage.message_id.
usageTokenUsageToken counts for this turn.
stop_reasonstringWhy the turn ended ("end_turn", "max_tokens", etc.).

​
Tool Protocol

Tools are functions that the client can execute on behalf of the agent. The flow is:
  1. Client registers tools via StartSession.tools, RegisterTools, or UserMessage.tools.
  2. During a turn, the server sends a ToolRequest asking the client to execute a tool.
  3. The client executes the tool and sends back a ToolResult.
  4. The agent incorporates the result and continues reasoning.

​
RegisterTools

Dynamically add or remove tools mid-session. Typical use: when a sim container starts, the IDE discovers its MCP tools and registers them with the session.
FieldTypeDescription
sourcestring (optional)Identifies the tool set owner (e.g. container ID). Tools prefixed with "{source}__" are replaced.
toolsToolSchema[]Replacement tool list. Empty list = unregister all tools from this source.
system_contextstring (optional)Workflow guidance for this tool set.

​
ToolRequest (server to client)

FieldTypeDescription
tool_call_idstringUnique ID for this tool invocation.
tool_namestringName of the tool to execute.
parametersStructJSON parameters for the tool.
timeout_msuint32Maximum execution time.

​
ToolResult (client to server)

FieldTypeDescription
tool_call_idstringMatches the ToolRequest.tool_call_id.
successboolWhether execution succeeded.
resultstringOutput text from the tool.
exit_codeint32 (optional)Shell exit code if applicable.
truncatedboolWhether the output was truncated.
duration_msint64 (optional)Wall-clock execution time.

​
ToolSchema

Describes a tool that the client can execute.
FieldTypeDescription
namestringTool name.
descriptionstringHuman-readable description.
parameters_schemaStructJSON Schema for the tool’s parameters.
timeout_msuint32Default timeout.
categoryToolCategoryHintPHYSICAL or PURE (affects UI presence).

​
Permission Protocol

The server can request user approval before executing certain tools.
  1. Server sends ActivityUpdate with state "waiting_approval".
  2. Client shows an approval dialog to the user.
  3. Client sends PermissionDecision with the tool_call_id and the user’s decision.

​
WatchTeam

Stream worker lifecycle events for multi-agent task execution. 
# Watch events for a task
grpcurl -d '{"task_id": "task_abc123"}' localhost:8080 roz.v1.AgentService/WatchTeam
Events include WorkerStarted, WorkerPhase, WorkerToolCall, WorkerCompleted, WorkerFailed, and WorkerExited.

​
Other Response Types

MessageDescription
SessionErrorError with code, message, and retryable flag.
KeepalivePeriodic heartbeat with optional token usage.
PongResponse to client Ping.
ContextCompactedNotification that the context window was compacted (with before/after token counts).
PresenceHintUI visibility hint ("full", "mini", "hidden").
ActivityUpdateAgent state change ("thinking", "calling_tool", "idle", "waiting_approval").

​
Source Code

Proto definition: proto/roz/v1/agent.proto