Rust runtimes

​

Overview

​

The tokio runtime

• The time driver. A tracked server needs a tokio runtime with the time driver. The SDK times a rebuild of its tool registry with tokio::time::timeout, and tokio panics at such a timer on a runtime without the driver. rmcp uses timers too. #[tokio::main], #[tokio::test] and tokio::runtime::Runtime::new turn the time driver on. A runtime from tokio::runtime::Builder needs enable_time or enable_all.
• Hooks run on the runtime of the call. The SDK starts the identify, event_tags, event_properties and resolve_session_id hooks as Send tasks on the tokio runtime of the tool call, so it does not support the local feature of rmcp. The call never waits for these hooks, so a slow hook never delays a tool call. When the event is ready to go out, the SDK waits at most 30 seconds for each hook. It stops a hook that has not completed by then, and the event goes out without the value of that hook.
• Redaction hooks. redact_event and then redact_sensitive_information run on the tokio runtime that serves the call too, before the event leaves the process. They have no time limit (see Known limits).

​

Current-thread runtimes

use std::time::Duration;

// ... serve until the server stops ...
let delivered = agentcat.shutdown(Duration::from_secs(5)).await;
if !delivered {
    // Some events did not go out within 5 s.
}

​

The delivery thread

• The queue holds at most 10,000 events. When it is full, the SDK drops the oldest event.
• At most 5 events of a handle are in progress at a time.
• The SDK tries a failed send 3 more times, after 1, 2 and 4 seconds. Each attempt has a timeout of 10 seconds.

​

Stdio servers

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Reads AGENTCAT_PROJECT_ID, and AGENTCAT_API_URL when set. Without a project ID, the handle
    // builds events but sends none.
    let server = AgentCat::from_env(Options::default()).track(Demo);

    // Serve the wrapper where you served `Demo`.
    let running = server.serve(stdio()).await?;
    running.waiting().await?;
    Ok(())
}

​

Streamable HTTP servers

use std::sync::Arc;
use std::time::Duration;

use agentcat_sdk::{AgentCat, Options};
use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One handle for the whole process.
    let agentcat = AgentCat::new("proj_...", Options::default());

    // rmcp calls this closure for each new MCP session. Wrap each new server.
    let handle = agentcat.clone();
    let service = StreamableHttpService::new(
        move || Ok(handle.track(Calculator)),
        Arc::new(LocalSessionManager::default()),
        StreamableHttpServerConfig::default(),
    );
    let router = axum::Router::new().route_service("/mcp", service);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:8000").await?;
    tokio::select! {
        served = axum::serve(listener, router) => served?,
        _ = tokio::signal::ctrl_c() => {}
    }

    // Deliver the queued events before the process ends.
    agentcat.shutdown(Duration::from_secs(5)).await;
    Ok(())
}

​

Flush and shutdown

• AgentCat::flush(timeout) waits until the handle delivered every event that it took, for at most timeout. It returns true when that happened in time, and returns true at once when the handle has taken no event yet. Events still go out after a false.
• AgentCat::shutdown(timeout) does the same, then stops the handle for good: the handle drops every later event, for all its clones. A second shutdown after the first has ended returns true at once.
• AgentCat::flush_blocking and AgentCat::shutdown_blocking block the calling thread instead. They need no tokio runtime. On a thread of a runtime, they block that thread.

​

The drain of the last drop

• The process ends at once. The drain does not run after std::process::exit, or after a panic with panic = "abort".
• A hook holds a clone of its handle. The handle holds its options, and the options hold the hook, so the handle never drops. Let the hook capture only what it needs, or call shutdown before the process ends. A tool reaches its handle through CallContext::agentcat and needs no clone.

​

Environment variables

​

Logging

[2026-10-28T09:15:02.137Z] [sdk=1.0.0 rust=1.88.0 rmcp=3.6.0] Successfully sent event ...

use agentcat_sdk::{LogDestination, Options};

let options = Options::default().log_destination(LogDestination::Tracing);

• The target. The tracing events have the target agentcat. A line about a failure or an error is an ERROR event. A warning is a WARN event, and any other line is an INFO event.
• A global subscriber. The delivery thread of the handle emits the events, so set a global subscriber, for example with tracing::subscriber::set_global_default. A subscriber that with_default sets on another thread does not see them.
• One destination for the process. The log destination applies to the whole process. The first handle built in the process decides it.

​

Logging on stdio servers