Quickstart

Get up and running with Splinter in 5 minutes

Get Splinter running in your project in under 5 minutes.

Installation

pip install splinter-agent

Then install your LLM provider:

pip install openai              # OpenAI (GPT-4, GPT-4o)
pip install anthropic           # Anthropic (Claude)
pip install google-generativeai # Google (Gemini)
pip install openai              # Grok (uses OpenAI SDK)

Basic Usage

Single Agent

from splinter import Splinter

# Create with safety limits
s = Splinter(
    openai_key="sk-...",
    max_budget=5.0,   # Stop at $5
    max_steps=50,     # Stop after 50 LLM calls
)

# Run an agent
result = await s.run("researcher", "Find the top 3 AI trends for 2024")

# Check your spend
print(f"Cost: ${s.cost:.4f} | Steps: {s.steps}")

Multi-Agent Pipeline

from splinter import Splinter

s = Splinter(openai_key="sk-...", max_budget=10.0)

# Define agents
s.add_agent("researcher", "Research topics. Output JSON: {findings: []}")
s.add_agent("writer", "Write articles. Output JSON: {article: string}")

# Run pipeline (researcher → writer)
result = await s.pipeline(
    ["researcher", "writer"],
    input={"topic": "AI trends"}
)

print(result.outputs["writer"])

Environment Variables

Instead of passing keys directly, use environment variables:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."
export XAI_API_KEY="xai-..."

Then just:

s = Splinter(max_budget=5.0)  # Keys auto-detected from env

Adding Controls

Budget + Time Limits

from splinter import Splinter
from splinter.types import ExecutionLimits

s = Splinter(
    openai_key="sk-...",
    max_budget=10.0,
    max_steps=100,
)

# Or use ExecutionLimits for more control
limits = ExecutionLimits(
    max_budget=10.0,
    max_steps=100,
    max_time_seconds=600,  # 10 minute timeout
)

Loop Detection

from splinter.types import LoopDetectionConfig

s = Splinter(
    openai_key="sk-...",
    loop_detection=LoopDetectionConfig(
        max_repeated_outputs=3,  # Same output 3x = loop
        max_no_state_change=5,   # No progress 5x = loop
    ),
)

Adding Coordination

Shared State

from splinter.coordination import SharedState

state = SharedState(initial_data={"topic": "AI"})

# Agents read and write
state.set("research.findings", ["trend1", "trend2"])
findings = state.get("research.findings")

Checkpoints

from splinter.coordination import CheckpointManager, FileCheckpointStorage

mgr = CheckpointManager(storage=FileCheckpointStorage("./checkpoints"))

# Save progress
mgr.create_checkpoint(workflow_id="wf-1", step=3, state=state)

# Resume after crash
checkpoint = mgr.get_latest_checkpoint("wf-1")

Next Steps

Control Layer

Learn about budget limits, rate limiting, circuit breakers, and more

Coordination Layer

Learn about shared state, checkpoints, handoffs, and more

Splinter Cloud

Add live dashboard and remote control with an API key

API Reference

Full API documentation