> ## 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.

# Go SDK

> Write Nagare plugins in Go: register tools, chat channels, and system prompts.

## Installation

```bash theme={null}
mkdir hello-plugin && cd hello-plugin
go mod init example.com/hello-plugin
go get github.com/smtdfc/nagare/pkgs/plugin/sdk
```

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

## Example: tool plugin

```go main.go theme={null}
package main

import (
	"context"
	_ "embed"
	"fmt"

	sdk "github.com/smtdfc/nagare/pkgs/plugin/sdk"
)

//go:embed metadata.json
var metadata string

type GreetArgs struct {
	Name string `json:"name" jsonschema:"description=Name of the person to greet"`
}

type GreetResult struct {
	Message string `json:"message"`
}

func main() {
	ctx := context.Background()
	plugin := sdk.NewPlugin()

	if _, err := plugin.LoadMetadata(metadata); err != nil {
		panic(err)
	}

	greet := sdk.DefineTool[GreetArgs, GreetResult](
		"greet_tool",
		"Generate a greeting for a person.",
		func(ctx *context.Context, args *GreetArgs) (*GreetResult, error) {
			return &GreetResult{Message: fmt.Sprintf("Hello, %s!", args.Name)}, nil
		},
		[]string{"greeting"},
	)

	err := plugin.Start(ctx, func() {
		if err := plugin.Handshake(ctx); err != nil {
			plugin.Logger.Error("handshake failed", "error", err)
			return
		}

		_ = plugin.RegisterToolCategories(ctx, map[string]string{
			"greeting": "Greeting tools",
		})

		if err := plugin.RegisterPluginTool(ctx, greet); err != nil {
			plugin.Logger.Error("register tool failed", "error", err)
		}
	})
	if err != nil {
		plugin.Logger.Error("plugin stopped", "error", err)
	}
}
```

The `metadata.json` for this plugin must include `"features": ["plugin_tool"]`.

Build and install:

```bash theme={null}
nagare plugin build
# Generates <package_name>.nagare_plugin
```

## Lifecycle

1. `sdk.NewPlugin()` creates the client and reads `NAGARE_PLUGIN_LOG_FILE`, `NAGARE_PLUGIN_CONFIG_DIR`, `NAGARE_PLUGIN_DATA_DIR`.
2. `LoadMetadata(raw)` loads and validates metadata. Usually used with `//go:embed metadata.json`.
3. `Start(ctx, onStart)` connects to the gateway, calls `onStart`, and waits until the connection closes.
4. Inside `onStart`, **always call `Handshake(ctx)` first** before any other command.

## API reference

### Tools

| Function | Description |
| - | - |
| `sdk.DefineTool[I, O](name, description, callback, categories)` | Define a tool. Parameter schema is auto-generated from type `I`. Callback signature: `func(ctx *context.Context, args *I) (*O, error)`. |
| `RegisterPluginTool(ctx, tool)` | Register a tool with the gateway. Requires the `plugin_tool` feature. |
| `RegisterToolCategories(ctx, map[string]string)` | Register new categories (name -> description) so the agent can discover tools. |

Each tool call has a maximum timeout of 60 seconds.

### Chat (feature `chat`)

| Function / field | Description |
| - | - |
| `PrepareChatChannel(ctx, channelID)` | Create or reopen a chat channel with an ID set by the plugin (e.g., Telegram chat ID). |
| `SendChatMessage(ctx, channelID, text)` | Send a user message to the agent. |
| `ResetChatChannel(ctx, channelID)` | Start a new session for the channel. |
| `RegisterChatListener(ctx, sessionID)` | Listen to messages from an existing session. |
| `SubmitToolApproval(ctx, channelID, requestID, accept)` | Send a tool approval result. |
| `OnReceivedChatMessage` | Callback `func(channelID, chunk string)` receiving each response chunk as JSON. See [message format](https://docs.nagare.smtdfc.net/en/plugins/overview.md#chat-messages). |

### Other

| Function / field | Description |
| - | - |
| `GetListModelProvider(ctx)` | Returns `map[id]name` of model providers. Requires the `model_provider` feature. |
| `InjectSystemPrompt(ctx, content)` | Inject the plugin's system prompt (max 64 KiB, replaces previous prompt). Requires the `system_prompt` feature. Must be re-injected after reconnecting. |
| `ClearSystemPrompt(ctx)` | Clear the plugin's system prompt. |
| `Logger` | `*slog.Logger` writing JSON logs to stdout and the plugin's log file. |
| `ConfigDir`, `DataDir` | Plugin-specific configuration and data directories. |


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