starflask

Rust SDK for the Starflask AI agent platform.

Installation

[dependencies]
starflask = "0.1"

Quick start

use starflask::Starflask;

#[tokio::main]
async fn main() -> Result<(), starflask::Error> {
    let sf = Starflask::new("sk_...", None)?;

    // List your agents
    let agents = sf.list_agents().await?;

    // Send a message and wait for the response
    let session = sf.query(&agents[0].id, "Hello!").await?;
    println!("{:?}", session.result);

    Ok(())
}

Query

Send a chat message to an agent and wait for the response. The SDK handles session creation and polling automatically.

// Simple query — uses the agent's soul prompt
let session = sf.query(&agent_id, "What can you do?").await?;
println!("{:?}", session.result);

// Query with a specific persona
let session = sf.query_with_persona(
    &agent_id,
    "Design a retro game UI palette",
    Some("palette_generator_reactive"),
).await?;

When you specify a persona, the agent's soul prompt is still used as the base system context, but the named persona's prompt is appended — giving the agent a specific behavioral mode for that query.

Hooks

For structured workflows where an agent pack defines event-specific persona templates with variable substitution, use hooks:

// Fire and wait
let session = sf.fire_hook_and_wait(
    &agent_id,
    "generate_palette",
    serde_json::json!({ "premise": "sunset over the ocean" }),
).await?;

// Fire without waiting
let session = sf.fire_hook(&agent_id, "heartbeat", serde_json::json!({})).await?;

Packs

Packs define an agent's soul, personas, and hooks. Use provision_pack to create and install a pack in one step.

let result = sf.provision_pack(&agent_id, serde_json::json!({
    "soul": {
        "name": "my_agent",
        "description": "A helpful assistant",
        "content": "You are a helpful assistant.",
        "tags": ["assistant"],
    },
    "personas": [
        {
            "name": "default",
            "description": "Default persona",
            "content": "Respond concisely and helpfully.",
        }
    ],
    "pack": {
        "name": "my_pack",
        "description": "My agent pack",
        "hooks": {
            "greet": {
                "persona": "default",
                "template": "Say hello to {{name}}.",
            }
        }
    }
})).await?;
println!("Provisioned with hash: {}", result.content_hash);

Provisioning is idempotent — calling it again with the same content is a no-op (matched by content_hash). Calling it with updated content replaces the agent's existing pack.

If you already have a content_hash from a previous provision, you can install it directly:

sf.install_agent_pack(&agent_id, &content_hash).await?;

Features

• Agents — create, list, update, activate/deactivate, and delete agents
• Query — send messages to agents with automatic session polling, optional persona selection
• Hooks — fire hook events with payload variable substitution
• Sessions — list and inspect session history
• Packs — install and provision agent packs
• Integrations — manage platform integrations (Discord, etc.)
• Tasks — create and list scheduled agent tasks
• Memories — list agent memories

Custom base URL

let sf = Starflask::new("sk_...", Some("https://starflask.xyz/api"))?;

License

MIT