Plugin API Reference

Complete reference for all gRPC services, messages, and enums in the AgentPlatform plugin system.

Plugin Service (required)

Every plugin must implement this service. It handles registration, health checks, and manifest discovery.

Proto file: proto/plugin.proto

Register

Called by the platform when a workspace starts and the plugin is loaded. The platform sends configuration values and environment variables; the plugin returns its name and capabilities.

rpc Register(RegisterRequest) returns (RegisterResponse)

RegisterRequest

RegisterResponse

Health

Health check polled periodically by the platform.

rpc Health(HealthRequest) returns (HealthResponse)

HealthResponse

GetManifest

Returns the plugin's manifest HCL so remote plugins can be discovered from just a network address.

rpc GetManifest(GetManifestRequest) returns (GetManifestResponse)

GetManifestResponse

Enums

Capability

Status

Settings API (HTTP)

Per-workspace plugin settings with form-driven UI. These values override manifest defaults but are overridden by workspace HCL config {} blocks.

Config Merge Order

When a workspace starts, plugin configuration is merged in this order (later wins):

1. Plugin manifest defaults — default values from FieldDef in the manifest
2. Workspace settings — values saved via the Settings API
3. Workspace HCL config — config {} block in workspace HCL (highest priority)

GET /api/v1/workspaces/{id}/settings

Returns all plugin settings for the workspace, along with config schemas.

Response: Array of plugin setting objects:

[
  {
    "name": "anthropic",
    "schema": [
      {"name": "api_key_env", "type": "string", "required": true, ...}
    ],
    "settings": {"api_key_env": "ANTHROPIC_API_KEY", "default_model": "claude-sonnet-4-6"}
  }
]

PUT /api/v1/workspaces/{id}/settings/{plugin}

Save settings for a single plugin in a workspace. Validates values against the plugin's manifest schema.

Request:

{"settings": {"api_key_env": "ANTHROPIC_API_KEY", "default_model": "claude-sonnet-4-6"}}

Success response: {"status": "saved"}

Validation error response:

{"error": "validation failed", "fields": {"api_key_env": "required"}}

GET /api/v1/workspaces/{id}/settings/{plugin}/options/{field}?q=

Proxy endpoint for dynamic select options. Forwards the request to the field's api_source URL and returns the result. Used by searchable select components to avoid CORS issues.

Expected upstream response format:

[{"value": "us-east-1", "label": "US East (N. Virginia)"}]

ToolProvider Service

Provides custom tools that the agent can call during conversations.

Proto file: proto/tool.proto

ListTools

Returns the list of tools this plugin provides. Called once after Register.

rpc ListTools(ListToolsRequest) returns (ListToolsResponse)

ListToolsResponse

ToolDefinition

ExecuteTool

Called when the agent invokes a tool. The platform sends the tool name and JSON arguments; the plugin executes the tool and returns the result.

rpc ExecuteTool(ExecuteToolRequest) returns (ExecuteToolResponse)

ExecuteToolRequest

ExecuteToolResponse

LLMProvider Service

Provides LLM completions with streaming support. The platform sends a conversation and the plugin streams back tokens and events.

Proto file: proto/llm.proto

Complete

Runs a completion request and streams back response events.

rpc Complete(CompleteRequest) returns (stream CompleteResponse)

CompleteRequest

Message

ToolCall

CompleteResponse (streamed)

A oneof event containing one of:

ToolCallDelta

FinishReason

ViewProvider Service

Provides UI views rendered in the workspace dashboard. Views are described using HCL components — plugins never produce HTML.

Proto file: proto/view.proto

ListViews

Returns the views this plugin provides. Called once after Register.

rpc ListViews(ListViewsRequest) returns (ListViewsResponse)

ListViewsResponse

ViewDefinition

RouteDefinition

RenderView

Returns HCL component definitions for a view. Called when the user navigates to the view.

rpc RenderView(RenderViewRequest) returns (RenderViewResponse)

RenderViewRequest

RenderViewResponse

HandleRoute

Handles a proxied HTTP request. The platform forwards matching HTTP requests to this RPC.

rpc HandleRoute(RouteRequest) returns (RouteResponse)

RouteRequest

RouteResponse

HandleStream

Bidirectional streaming RPC for WebSocket communication. The platform bridges browser WebSocket connections to this RPC. The platform never inspects the data — it acts as a dumb relay.

rpc HandleStream(stream StreamMessage) returns (stream StreamMessage)

StreamMessage

The first message from the platform contains metadata:

After the initial metadata message, subsequent messages carry data only — the raw bytes from the browser's WebSocket.

LifecycleHook Service

Intercepts agent lifecycle events. Hooks can observe, modify, or cancel events as they flow through the agent runtime.

Proto file: proto/lifecycle.proto

OnEvent

Called for each lifecycle event. The plugin can continue, modify, or cancel the event.

rpc OnEvent(LifecycleEvent) returns (LifecycleEventResponse)

LifecycleEvent

EventType

LifecycleEventResponse

Action

Lifecycle Event Payloads

Each event type has a specific JSON payload shape:

AGENT_START / AGENT_END

{
  "agent_name": "triage",
  "input": "user's message"
}

TURN_START / TURN_END

{
  "agent_name": "triage",
  "turn_number": 1
}

LLM_REQUEST

{
  "model": "claude-sonnet-4-6",
  "messages": [...],
  "tools": [...]
}

LLM_RESPONSE

{
  "content": "assistant response text",
  "tool_calls": [{"id": "...", "name": "...", "arguments_json": "..."}],
  "finish_reason": "stop"
}

TOOL_CALL

{
  "tool_name": "get_weather",
  "arguments_json": "{\"city\":\"SF\"}"
}

TOOL_RESULT

{
  "tool_name": "get_weather",
  "result_json": "{\"temperature\":72}",
  "is_error": false
}

HANDOFF

{
  "from_agent": "triage",
  "to_agent": "specialist",
  "context": "..."
}

PlatformHost Service (callback)

A callback service provided by the platform to plugins. Plugins call into this service to invoke platform capabilities like running agent conversations. The platform passes the address via the PLATFORM_HOST_ADDR environment variable (local plugins) or RegisterRequest.env_vars (remote plugins).

Proto file: proto/platform.proto

RunConversation

Runs an agent conversation in the workspace. The plugin sends input and optional history, and the platform streams back events.

rpc RunConversation(ConversationRequest) returns (stream ConversationEvent)

ConversationRequest

ChatMessageProto

ConversationEvent (streamed)

Event types: