Installation
Thenagare_plugin crate is in the Nagare repository. Add it to your Cargo.toml:
Cargo.toml
[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"
metadata.json as described in Plugin Overview.
Example: tool plugin
src/main.rs
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
}
nagare plugin build
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. |