Protocol Overview
The Palyra ecosystem relies on two primary schema formats to govern data exchange:- Protobuf (gRPC/Internal): Used for high-performance service-to-service communication (e.g., between
palyradandpalyra-browserd) and for defining core entity models. - JSON Envelopes (Web/External): Used for the Web Console API, A2UI (Agent-to-UI) updates, and external webhooks.
Multi-Language Consistency
To prevent drift between the Rust backend and various client implementations, Palyra utilizes a “Schema-First” approach. Source-of-truth.proto files are used to generate stubs for all supported languages.
| Language | Generated Stub Path | Validation Tool |
|---|---|---|
| Rust | schemas/generated/rust/protocol_stubs.rs | rustc |
| Kotlin | schemas/generated/kotlin/ProtocolStubs.kt | kotlinc |
| Swift | schemas/generated/swift/ProtocolStubs.swift | swiftc |
Code-to-Entity Mapping: Protocol Generation
The following diagram illustrates how the build system transforms Protobuf definitions into language-specific entities used throughout the codebase. Sources: scripts/protocol/generate-stubs.ps1#82-91, schemas/generated/rust/protocol_stubs.rs#1-7, schemas/generated/kotlin/ProtocolStubs.kt#1-4, schemas/generated/swift/ProtocolStubs.swift#1-3Protobuf Service Definitions
The core services of Palyra are defined in theschemas/proto directory. These definitions include both the RPC methods and the message structures (requests/responses) they exchange.
- GatewayService: Manages the lifecycle of Runs, message routing, and agent bindings schemas/proto/palyra/v1/gateway.proto#7-29.
- BrowserService: Controls the
palyra-browserdinstance, including session management, navigation, and DOM observation schemas/proto/palyra/v1/browser.proto#7-42. - ApprovalsService: Handles the querying and exporting of human-in-the-loop approval records schemas/proto/palyra/v1/gateway.proto#31-35.
- VaultService: Provides secure storage for secrets across different scopes schemas/proto/palyra/v1/gateway.proto#37-42.
JSON Envelope Schemas & A2UI Protocol
Beyond gRPC, Palyra uses JSON-based protocols for UI interaction and external integrations. These are characterized by “Envelopes” that wrap various payload types with consistent metadata.- A2UI (Agent-to-UI): A specialized protocol for streaming UI state updates from the agent to the Web Console. It supports incremental patches to minimize bandwidth.
- Webhook Envelopes: Standardized formats for receiving events from Discord, Slack, or Telegram, including replay protection signatures.
- Config Export/Import: JSON representations of the
palyra.tomlconfiguration used for migrations and backups.
Validation Pipeline
Palyra enforces protocol integrity through a multi-stage validation pipeline triggered during CI. This ensures that any change to a.proto file is valid and that all generated stubs compile correctly in their respective languages.
Code-to-Entity Mapping: Validation Workflow
This diagram maps the validation logic to the scripts and tools responsible for enforcing the contract.Key Validation Steps:
- Protoc Validation: Uses
protocto verify that.protofiles are syntactically correct and imports are resolvable scripts/protocol/validate-proto.ps1#57-66. - Stub Drift Detection: Checks if the generated files in the repository match what the current generator script produces. If they differ, the CI fails scripts/protocol/check-generated-stubs.ps1#14-21.
- Language-Specific Compilation:
- Rust: Validates stubs using
rustc --edition=2021scripts/protocol/validate-rust-stubs.ps1#24-30. - Kotlin: Validates stubs using
kotlincto produce a temporary JAR scripts/protocol/validate-kotlin-stubs.ps1#24-29. - Swift: Validates stubs using
swiftc -emit-modulescripts/protocol/validate-swift-stubs.sh#20-21.
- Rust: Validates stubs using