Stigmer SDK

Multi-language SDKs for defining AI agent blueprints for the Stigmer platform.

Overview

Stigmer SDK provides idiomatic libraries for multiple programming languages to define agent configurations. Each SDK converts agent definitions into a standardized manifest format that the Stigmer CLI reads and deploys.

Architecture: The Synthesis Model

The Stigmer SDK follows a "Synthesis Model" architecture:

1. SDK = Config Generator: Your code collects agent configuration (skills, MCP servers, sub-agents, environment)
2. Automatic Serialization: On program exit, SDK auto-writes manifest.pb
3. CLI Reads & Deploys: Stigmer CLI reads the manifest and deploys to the platform

┌─────────────────┐
│   Your Code     │  Define agent blueprint
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   SDK Library   │  Collect configuration
└────────┬────────┘
         │ (auto-synth on exit)
         ↓
┌─────────────────┐
│  manifest.pb    │  SDK-CLI contract
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  Stigmer CLI    │  Deploy to platform
└─────────────────┘

Key Benefits:

• No manual serialization calls
• Type-safe, language-idiomatic APIs
• Single source of truth (your code)
• CLI handles all platform communication

Available SDKs

Go SDK

Status: ✅ Ready for Production
Location: go/
Installation:

go get github.com/leftbin/stigmer-sdk/go

Quick Example:

package main

import (
    "github.com/leftbin/stigmer-sdk/go/agent"
    "github.com/leftbin/stigmer-sdk/go/skill"
    "github.com/leftbin/stigmer-sdk/go/internal/synth"
)

func main() {
    defer synth.AutoSynth()  // Auto-writes manifest.pb on exit
    
    myAgent, _ := agent.New(
        agent.WithName("code-reviewer"),
        agent.WithInstructionsFromFile("instructions.md"),
    )
    
    myAgent.AddSkill(skill.Platform("coding-standards"))
}

Go SDK Documentation →

Python SDK

Status: 🚧 Coming Soon
Location: python/

Currently available in the Stigmer monorepo. Migration to this public repository is planned for a future release.

TypeScript SDK

Status: 📋 Planned
Location: typescript/

TypeScript SDK is planned for future development. Watch this repository for updates.

SDK-CLI Contract: Manifest Proto

All SDKs communicate with the Stigmer CLI via a standardized manifest proto format:

Buf Schema Registry: buf.build/leftbin/stigmer

The manifest proto defines:

• Agent blueprint (instructions, metadata)
• Skills (platform, org, or inline)
• MCP servers (stdio, Docker, HTTP)
• Sub-agents (inline or referenced)
• Environment variables

This contract allows:

• Multiple SDK languages with consistent behavior
• CLI independence from SDK implementation details
• Version compatibility guarantees via proto breaking change detection

Getting Started

1. Choose your language: Go (available now), Python (coming soon), TypeScript (planned)
2. Install the SDK: Follow language-specific installation instructions
3. Define your agent: Use the SDK's idiomatic API
4. Deploy with CLI: Run stigmer up to deploy your agent

Documentation

• Complete Documentation Index: docs/README.md - All SDK documentation
• Go SDK: go/README.md - Go SDK quick start
  • Go SDK Documentation - Complete Go SDK docs
  • Buf Dependency Guide - Using Buf Schema Registry
  • Migration Guide - Proto-agnostic migration
  • Proto Mapping Reference - CLI conversion reference
• Python SDK: python/README.md - Python SDK overview
  • Python SDK Documentation - Complete Python SDK docs
• Contributing: CONTRIBUTING.md

Features Across All SDKs

Agent Configuration

• Load instructions from files or inline
• Icon and description metadata
• Organization scoping

Skills

• Platform skills: Reference Stigmer's built-in skills
• Org skills: Reference your organization's skills
• Inline skills: Define skills directly in your repository

MCP Servers

• Stdio servers: Node.js scripts, Python packages, binaries
• Docker servers: Containerized MCP servers
• HTTP servers: Remote MCP endpoints
• Environment placeholder support for secrets

Sub-Agents

• Inline sub-agents: Define sub-agents with their own configuration
• Referenced sub-agents: Reference deployed agent instances
• Tool selection and skill inheritance

Environment Variables

• Secret and non-secret variables
• Default values
• Runtime overrides via CLI

Repository Structure

stigmer-sdk/
├── README.md              # This file
├── LICENSE                # Apache 2.0 License
├── CONTRIBUTING.md        # Contribution guidelines
│
├── docs/                  # SDK-wide documentation
│   ├── README.md          # Documentation index
│   ├── guides/
│   ├── implementation/    # Implementation reports
│   └── references/
│
├── go/                    # Go SDK
│   ├── README.md          # Go SDK quick start
│   ├── docs/              # Go-specific documentation
│   │   ├── README.md
│   │   ├── guides/
│   │   ├── implementation/
│   │   └── references/
│   ├── agent/
│   ├── skill/
│   ├── mcpserver/
│   ├── subagent/
│   ├── environment/
│   └── examples/
│
├── python/                # Python SDK (future)
│   ├── README.md
│   └── docs/              # Python-specific documentation
│       ├── README.md
│       └── implementation/
│
└── typescript/            # TypeScript SDK (future)
    └── README.md

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Testing guidelines
• Pull request process
• Code style conventions

License

Apache 2.0 License - see LICENSE for details.

Links

• Stigmer Platform: stigmer.ai
• Documentation: docs.stigmer.ai
• Buf Schema Registry: buf.build/leftbin/stigmer
• Main Repository: github.com/leftbin/stigmer

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join our Discord (link TBD)

---

Note: This SDK is currently in active development. APIs may change before the 1.0 release. See CHANGELOG.md for version history.