Production infrastructure for AI agents

Website · Documentation · Guides · Core · Template · Discord

systemprompt-client

The outside edge of a systemprompt.io deployment. Every CLI and external service reaches the server through one typed HTTP surface, never a repository or a database. What runs the deployment stays behind the API, and callers hold requests, not internals.

Layer: Shared, foundational types and traits with no dependencies on other layers. Part of the systemprompt-core workspace.

What it does

SystempromptClient wraps a pre-configured reqwest::Client and exposes typed methods for the routes declared in systemprompt-models::ApiPaths. External applications talk to a running deployment without linking against its business logic. Requests carry typed identifiers (ContextId, JwtToken), responses deserialize into shared models, and failures resolve to a single ClientError enum.

RemoteCliExecutor streams remote CLI command output over server-sent events into a caller-supplied OutputSink, so a local shell can drive a command running on the deployment and see its output arrive line by line.

Module map

Error model

is_retryable() returns true for Timeout, ServerUnavailable, and HttpError.

Usage

[dependencies]
systemprompt-client = "0.21"

use systemprompt_client::{SystempromptClient, ClientResult};
use systemprompt_identifiers::JwtToken;

#[tokio::main]
async fn main() -> ClientResult<()> {
    // Create client with authentication
    let token = JwtToken::new("your-jwt-token");
    let client = SystempromptClient::new("https://api.systemprompt.io")?
        .with_token(token);

    // List available agents
    let agents = client.list_agents().await?;
    for agent in agents {
        println!("Agent: {}", agent.name);
    }

    // Work with contexts
    let contexts = client.list_contexts().await?;
    if let Some(ctx) = contexts.first() {
        let tasks = client.list_tasks(ctx.context_id.as_ref()).await?;
        println!("Found {} tasks", tasks.len());
    }

    // Health check (non-failing)
    if client.check_health().await {
        println!("Server is healthy");
    }

    Ok(())
}

use systemprompt_client::SystempromptClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SystempromptClient::new("http://localhost:9999")?;
    let agents = client.list_agents().await?;
    for agent in agents {
        println!("agent: {}", agent.name);
    }
    Ok(())
}

API Operations

Error Handling

All fallible operations return ClientResult<T>. Pattern match on ClientError for specific handling:

use systemprompt_client::{ClientError, ClientResult};

async fn handle_errors(client: &SystempromptClient) -> ClientResult<()> {
    match client.list_agents().await {
        Ok(agents) => { /* success */ }
        Err(ClientError::AuthError { message }) => {
            eprintln!("Authentication failed: {}", message);
        }
        Err(ClientError::ApiError { status, message, .. }) => {
            eprintln!("API error {}: {}", status, message);
        }
        Err(e) if e.is_retryable() => {
            // Implement retry logic
        }
        Err(e) => return Err(e),
    }
    Ok(())
}

Configuration

Timeout

Default timeout is 30 seconds. Custom timeout:

let client = SystempromptClient::with_timeout("https://api.example.com", 60)?;

Authentication

Token can be set at construction or later:

// At construction (builder pattern)
let client = SystempromptClient::new(url)?.with_token(token);

// After construction (mutation)
let mut client = SystempromptClient::new(url)?;
client.set_token(token);

Dependencies

License

BSL-1.1 (Business Source License). Source-available for evaluation, testing, and non-production use. Production use requires a commercial license. Each version converts to Apache 2.0 four years after publication. See LICENSE.

systemprompt.io · Documentation · Guides · Live Demo · Template · crates.io · docs.rs · Discord

Shared layer · Own how your organization uses AI.