Gestalt Rust SDK

Use the Rust SDK to build compiled Gestalt providers with typed routers, serde input and output types, and schema-derived catalog metadata.

The package is published to crates.io as gestalt-sdk, while Rust code imports the crate as gestalt.

cargo add gestalt-sdk --rename gestalt
cargo add serde --features derive
cargo add schemars --features derive

API sections

The docs.rs reference is organized around the provider-authoring workflow. Most provider code imports from the crate root after renaming gestalt-sdk to gestalt.

Quick start

Register typed operations on a router. The router dispatches requests and emits catalog metadata for gestaltd.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Default)]
struct SearchProvider;

#[gestalt::async_trait]
impl gestalt::Provider for SearchProvider {}

#[derive(Deserialize, JsonSchema)]
struct SearchInput {
    #[schemars(description = "Search query")]
    query: String,
}

#[derive(Serialize, JsonSchema)]
struct SearchOutput {
    results: Vec<String>,
}

fn router() -> gestalt::Result<gestalt::Router<SearchProvider>> {
    gestalt::Router::new().register(
        gestalt::Operation::<SearchInput, SearchOutput>::new("search")
            .method("GET")
            .title("Search"),
        |_: Arc<SearchProvider>, input, _request| async move {
            Ok::<_, gestalt::Error>(gestalt::ok(SearchOutput {
                results: vec![input.query],
            }))
        },
    )
}

gestalt::export_provider!(constructor = SearchProvider::default, router = router);

Fields are required unless they are modeled as Option<T> or have a serde default. Use schemars attributes for catalog descriptions.

Provider surfaces

Use Provider, Operation, Router, and export_provider! for integration providers. Use the other provider traits and export macros when you are serving a host-service backend.

The crate also exposes clients for sibling host services, including Cache, S3, Workflow, Agent, and App.

Calling sibling host services

Each host-service client connects from the environment with connect()/connect_named(name) and exposes one method per RPC with flattened parameters, plus a _raw sibling that takes the full request message. Optional parameters ride in a per-method options struct (for example AppInvokeOptions) whose default value leaves every option unset. Contextful clients (App, Agent, Workflow) accept a default request context through with_context(...); outgoing requests that leave the context unset get the default injected. Every client accepts a per-call deadline through with_timeout(...); unary calls that run past it fail with DEADLINE_EXCEEDED.

# async fn example(
#     params: serde_json::Map<String, serde_json::Value>,
# ) -> Result<(), Box<dyn std::error::Error>> {
#[derive(serde::Deserialize)]
struct Issue {
    id: u64,
}

let mut app = gestalt::App::connect().await?;
let data = app
    .invoke(
        "github".to_string(),
        "get_issue".to_string(),
        Some(params),
        gestalt::app::AppInvokeOptions::default(),
    )
    .await?;
let issue: Issue = serde_json::from_value(data)?;
# let _ = issue.id;
# Ok(())
# }

AgentProvider implementations receive and return native structs such as CreateAgentProviderTurnRequest, AgentSession, AgentTurn, and AgentTurnEvent. Structured payload fields use serde_json::Value and timestamp fields use SystemTime; the SDK runtime owns transport serialization at the transport boundary. Workflow builders such as new_bound_workflow_target, new_workflow_definition, new_workflow_run, and new_workflow_signal accept SDK-owned input structs and preserve request shape without asking provider code to assemble transport objects.

Public surface

The crate exposes higher-level authoring APIs:

• Provider, Request, Response, and ok(...) model integration providers.
• HTTPSubjectRequest and Provider::resolve_http_subject let executable apps map verified hosted HTTP requests to concrete subjects.
• Router and Operation register typed operations and derive catalog metadata from serde and schemars.
• IdentityProvider, CacheProvider, S3Provider, SecretsProvider, WorkflowProvider, AgentProvider, and RuntimeProvider model executable provider runtimes.
• Cache, S3, Workflow, Agent, and App call sibling host services.
• RuntimeMetadata lets provider runtimes describe their display metadata and version.
• Workflow builder inputs such as BoundWorkflowTarget, WorkflowStep, WorkflowActivation, WorkflowDefinition, WorkflowSignal, and WorkflowRun model provider-owned workflow state.

Package layout

This package intentionally lives outside the existing gestalt/ Cargo workspace so the SDK can evolve independently of the CLI crate graph.