sdk

README

Grateful Agents SDK

A Go toolkit for embedding tool-using AI agents in your application. The runner is small, provider-neutral, and host-driven: your code stays in charge of credentials, persistence, UI, approvals, policy, and deployment.

Builds and tests with Go 1.26.3.

Install

go get github.com/gratefulagents/sdk

Hello World

package main

import (
	"context"
	"fmt"

	"github.com/gratefulagents/sdk/pkg/agentsdk"
	sdkopenai "github.com/gratefulagents/sdk/pkg/agentsdk/providers/openai"
)

func main() {
	provider := sdkopenai.NewProviderWithConfig(sdkopenai.ProviderConfig{
		APIKey: "<your-api-key>",
	})
	runner := agentsdk.NewRunnerWithProvider(provider)

	result, err := runner.Run(context.Background(), &agentsdk.Agent{
		Name:         "hello",
		Model:        sdkopenai.DefaultChatModel,
		Instructions: "Reply with exactly: hello world",
	}, []agentsdk.RunItem{{
		Type:    agentsdk.RunItemMessage,
		Message: &agentsdk.MessageOutput{Text: "Say hello world."},
	}}, agentsdk.RunConfig{MaxTurns: 1})
	if err != nil {
		panic(err)
	}

	fmt.Println(result.FinalText())
}

Features

Each feature links to a focused doc with a runnable example.

Feature	What it does
Agent runtime	Multi-turn loop with tools, handoffs, approvals, retries, usage, and hooks.
Model abstraction	Custom Model/ModelProvider, MultiProvider, and provider-prefixed routing.
Providers	OpenAI (Responses/Chat), OpenAI OAuth, Anthropic API key/OAuth, OpenRouter, local gateways.
Tools	FunctionTool, JSON schemas, approvals, and tool policies.
Tool registry	Permission-aware built-in tools: shell, fs, search, git, LSP, web, and more.
MCP	Load .mcp.json stdio servers and expose their tools and resources.
Sandbox	Subprocess execution with a configurable, fail-closed boundary.
ChatLoop	Conversation helper for interactive multi-turn sessions.
Handoffs & sub-agents	Agent handoffs, Agent.AsTool, specialists, and async sub-agent tasks.
Guardrails	Input/output/tool guardrails with destructive-command and secret rules.
Structured output	JSON-schema prompting, validation, and custom parsing.
Streaming	Raw model deltas, run-item events, and final streamed result.
Context compaction	Local and provider-native history compaction with carry-forward guards.
Settings & routing	Reasoning/verbosity settings, mode routing, and role overrides.
Observability	Run/agent hooks, progress tracking, event streams, and request snapshots.
Errors & retries	Typed run errors, retry policy, and capped retry-after delays.
Costs	Usage mapping and per-provider cost estimation.
Policy	Permission and access-clamping primitives.
Memory	Optional memory stores and embedders.
Trace store	Filesystem trace persistence and OpenTelemetry bridging.

Run every feature example offline:

GRATEFUL_LIVE_TESTS=skip go test ./examples/features/...

Documentation

• Architecture — package boundaries and runtime flow.
• Security model — threat model and shipped defenses. Read before exposing tools to untrusted input.
• Development — local workflow and the live-test matrix.
• Feature inventory — full list of feature examples.
• CLI harness — evaluation, CI, and benchmark runs.

Testing

GRATEFUL_LIVE_TESTS=skip go test ./...   # deterministic, offline
go vet ./...
make verify-sdk-purity

Live example tests skip when credentials are missing. Set GRATEFUL_LIVE_TESTS=required to fail instead.

Contributing

See CONTRIBUTING.md. Report security issues via SECURITY.md, not public issues.

License

GPL-3.0-only. See LICENSE.