> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nagare.smtdfc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK

> Write Nagare plugins in Rust with the nagare_plugin crate.

## Installation

The `nagare_plugin` crate is in the Nagare repository. Add it to your `Cargo.toml`:

```toml Cargo.toml theme={null}
[package]
name = "hello-plugin"
version = "0.1.0"
edition = "2024"

[dependencies]
nagare_plugin = { git = "https://github.com/smtdfc/nagare" }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
schemars = "0.8"
```

Create `metadata.json` as described in [Plugin Overview](https://docs.nagare.smtdfc.net/en/plugins/overview.md#metadata-json).

## Example: tool plugin

```rust src/main.rs theme={null}
use std::collections::HashMap;

use nagare_plugin::{PluginClient, PluginError, define_tool};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

const METADATA: &str = include_str!("../metadata.json");

#[derive(Deserialize, JsonSchema)]
struct GreetArgs {
    /// Name of the person to greet
    name: String,
}

#[derive(Serialize)]
struct GreetResult {
    message: String,
}

#[tokio::main]
async fn main() -> Result<(), PluginError> {
    let client = PluginClient::new();
    client.load_metadata(METADATA)?;

    let greet = define_tool(
        "greet_tool",
        "Generate a greeting for a person.",
        |args: GreetArgs| -> Result<GreetResult, PluginError> {
            Ok(GreetResult { message: format!("Hello, {}!", args.name) })
        },
        vec!["greeting".to_string()],
    );

    let c = client.clone();
    client
        .start(|| async move {
            if c.handshake().await.is_err() {
                return;
            }

            let mut categories = HashMap::new();
            categories.insert("greeting".to_string(), "Greeting tools".to_string());
            let _ = c.register_tool_categories(categories).await;

            let _ = c.register_plugin_tool(greet).await;
        })
        .await
}
```

Build the package:

```bash theme={null}
nagare plugin build
```

The build command runs `cargo build --release --target-dir build` and packages the executable.

## API reference

| Function | Description |
| - | - |
| `PluginClient::new()` | Create a client (returns `Arc<PluginClient>`). Requires the `NAGARE_PLUGIN_LOG_FILE` and `NAGARE_PLUGIN_CONFIG_DIR` environment variables, which the gateway sets when running the plugin. |
| `load_metadata(raw)` | Load and validate `metadata.json`. |
| `start(on_start)` | Connect to the gateway, run `on_start`, and wait until the connection closes. |
| `handshake()` | Handshake with the gateway. Call this first inside `on_start`. |
| `define_tool(name, description, callback, categories)` | Define a tool. The argument type must implement `Deserialize` and `JsonSchema`, and the result type must implement `Serialize`. |
| `register_plugin_tool(tool)` | Register a tool. Requires the `plugin_tool` feature. |
| `register_tool_categories(map)` | Register tool categories (name -> description). |
| `prepare_chat_channel(channel_id)` | Create or reopen a chat channel. Requires the `chat` feature. |
| `send_chat_message(channel_id, text)` | Send a message to the agent. |
| `reset_chat_channel(channel_id)` | Start a new session for the channel. |
| `set_on_received_chat_message(cb)` | Callback `Fn(channel_id: String, chunk: String)` receiving responses as JSON. |
| `config_dir()` | Plugin-specific configuration directory. |

Each tool call has a maximum timeout of 60 seconds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.