palyrad), CLI, and sidecar services. These definitions are located in schemas/proto/palyra/v1/ and are used to generate stubs for Rust, Kotlin, and Swift.
The protocol version is managed by a major version constant schemas/generated/rust/protocol_stubs.rs#5-5.
Service Architecture Overview
The communication between Palyra components is primarily driven by gRPC over mTLS or QUIC. TheGatewayService acts as the central orchestrator, while specialized services handle domain-specific logic like browser automation, secret management, and node-to-node communication.
Data Flow Diagram: Service Interactions
Title: Service Communication and Data Flow Sources: schemas/proto/palyra/v1/gateway.proto#7-51, crates/palyra-cli/src/lib.rs#151-1631. Gateway Service (gateway.proto)
The GatewayService is the primary entry point for agent orchestration and session management. It handles the execution of “Runs” and the routing of messages between users and agents.
Key Methods
RunStream: A bidirectional stream for executing agent tasks. It consumesRunStreamRequestand producesRunStreamEventschemas/proto/palyra/v1/gateway.proto#9-10.RouteMessage: Handles high-level message dispatching across channels schemas/proto/palyra/v1/gateway.proto#16-16.ListAgents/CreateAgent: CRUD operations for agent identities and their context bindings schemas/proto/palyra/v1/gateway.proto#17-21.
Supporting Services in gateway.proto
| Service | Purpose | Key Entity |
|---|---|---|
ApprovalsService | Manages human-in-the-loop (HITL) authorization records schemas/proto/palyra/v1/gateway.proto#31-35. | ApprovalRecord |
VaultService | Secure storage for sensitive credentials and API keys schemas/proto/palyra/v1/gateway.proto#37-42. | VaultSecretMetadata |
CanvasService | Manages interactive UI bundles and state for agent-user collaboration schemas/proto/palyra/v1/gateway.proto#44-51. | CanvasBundle |
2. Browser Service (browser.proto)
The BrowserService (implemented by palyra-browserd) provides a gRPC interface over headless Chromium via CDP. It allows agents to perform complex web automation.
Implementation Mapping
Title: Browser Service Entity Mapping Sources: schemas/generated/rust/protocol_stubs.rs#61-172, schemas/generated/kotlin/ProtocolStubs.kt#36-126Key Functions
- Session Lifecycle:
CreateSessionandCloseSessionmanage the Chromium process and profile isolation schemas/generated/swift/ProtocolStubs.swift#137-142. - Interaction:
Navigate,Click,Type, andPressprovide the primitives for DOM interaction schemas/generated/swift/ProtocolStubs.swift#212-247. - Relay Mechanism:
RelayActionallows the browser extension to securely send events back to the daemon usingRelayActionRequestschemas/generated/kotlin/ProtocolStubs.kt#93-94.
3. Auth Service (auth.proto)
The AuthService manages authentication profiles, including OpenAI-compatible API keys and OAuth2 refresh flows.
Data Structures
AuthProfile: Represents a configured provider (e.g., Anthropic, OpenAI) with its associated credentials schemas/generated/rust/protocol_stubs.rs#17-17.OAuthRefreshState: Tracks the health and expiry of OAuth tokens used by connectors schemas/generated/rust/protocol_stubs.rs#45-45.
Service Methods
ListProfiles: Returns all configured auth identities schemas/generated/rust/protocol_stubs.rs#56-56.GetHealth: Provides aAuthHealthSummaryindicating which providers are currently reachable and authenticated schemas/generated/rust/protocol_stubs.rs#54-54.
4. Common and Infrastructure Definitions
common.proto
Contains shared types used across all services:
CanonicalId: A standard ULID/UUID wrapper for identifying runs, sessions, and messages schemas/proto/palyra/v1/gateway.proto#87-89.RunStreamEvent: The core event-sourcing message containingRunDelta,ToolCall, orMessageupdates schemas/proto/palyra/v1/gateway.proto#10-10.
Specialized Services
cron.proto: Defines theCronServicefor managing scheduled routines and misfire policies crates/palyra-cli/src/lib.rs#30-34.memory.proto: Defines theMemoryServicefor vector search, FTS5 ingestion, and learning candidate review crates/palyra-cli/src/lib.rs#36-40.node.proto: Defines theNodeServiceused for mTLS-backed node enrollment and capability invocation crates/palyra-cli/src/lib.rs#42-46.plugin.proto: Manages the lifecycle of WASM plugins and their capability grants crates/palyra-cli/src/lib.rs#119-122.
5. Cross-Language Stub Generation
The schemas are compiled into language-specific stubs usingscripts/protocol/generate-stubs.sh.
| Language | Generated File | Usage |
|---|---|---|
| Rust | protocol_stubs.rs | Used by palyrad and palyra CLI crates/palyra-cli/src/lib.rs#16-60. |
| Kotlin | ProtocolStubs.kt | Used by the Android mobile app schemas/generated/kotlin/ProtocolStubs.kt#1-4. |
| Swift | ProtocolStubs.swift | Used by the iOS/macOS desktop clients schemas/generated/swift/ProtocolStubs.swift#1-3. |