sagent🪄

A coding-agent CLI and strongly-typed Python library -- self-mutating, hot-swapping, multi-provider, with async tool calls and bidirectional recursive spawn.

Tutorial · Concepts · Providers · Tools · CLI · Sessions · Security · Architecture · API · Streaming · Compaction · Slack · Self-hosted · Showcase · Examples

Quick Start

# Mac:
#   # Required for quick install.
#   brew install uv
#   # Optional for improved performance.
#   brew install ripgrep fd

# Ubuntu/Debian:
#   # Required for quick install.
#   sudo apt-get install -y curl
#   curl -LsSf https://astral.sh/uv/install.sh | sh
#   # Optional for improved performance.
#   sudo apt-get install -y ripgrep fd-find

uv tool install sagent

sagent

Better CLI

Things Claude Code, Codex CLI, and Gemini CLI don't do:

• Async REPL. Chat with agents about jobs while those jobs run. No ctrl+b, no manual juggling.
• Hot self-mutation. Switch provider, model, or thinking effort mid-session in plain English. No restart.
• One CLI, every provider. Anthropic, OpenAI, Google, Moonshot, DashScope, MiniMax, OpenAI-compatible endpoints, self-hosted HuggingFace models, and a managed llama.cpp server, all behind one binary.
• Unified cost tracking. One USD total across every provider in a session; sub-agent costs roll up to the root. --max-budget-usd N caps the whole tree.
• Self-directing agent fleets. Agents retune their own runtime -- provider, model, thinking, context -- mid-task. A coordinator can do it to its workers over AgentSend: "switch to o1, crank thinking, recompact and drop the file reads."
• Recursive agent messaging. Any spawned agent can spawn and AgentSend to any peer, so coordination is a tree, not a star. Claude Code's experimental Agent Teams is flat (one lead, no nesting); Codex and Gemini have no peer messaging.
• Interruptible, detachable tasks. Tell a stuck task to stop, or detach one and let it keep running.
• Richer built-in tools. PaperSearch/PaperFetch walk citation graphs and fetch PDFs, multi-backend WebSearch, WebFetch with markdown extraction, atomic read/write tracking on file tools.
• Unix-aligned and pipeable. stdin, stdout, exit codes, and --output-format json are first-class. Pipe through jq, drop into ipython (same prompt_toolkit underneath).

Uniquely also an API

• One runtime, every surface. The same Agent class powers the CLI, your application code, and recursive sub-agents.
• Typed Python objects. Agent, Tool, Model, Provider, and Message are protocols and dataclasses you import, compose, and unit-test.
• Peer-to-peer agent messaging. Any spawned agent can AgentSend to any other named peer -- not just its parent. Like user input, peer messages preempt the receiving agent's tool calls, so no agent blocks waiting on a stuck child.

Use it as a library:

from sagent import tools
from sagent.agent import Agent
from sagent.lib.codec import immutable
from sagent.providers import Google

agent = Agent(
    model=Google.from_env().model("gemini-pro-3.1"),
    system="You are a scientist.",
    tools=[tools.Read(), tools.Glob(), tools.Grep()],
)
result = await agent.run(immutable({"prompt": "analyze the CSV in ./data/"}))
print(result.content)

Install

Sagent requires Python 3.12 or newer. ripgrep and fd-find are optional -- sagent has Python fallbacks when absent -- but recommended for faster Grep / Glob. PDF rendering uses the bundled pypdfium2 wheel and needs no system install. The Quick Start above installs the sagent CLI.

Add sagent to your own project as a library:

uv add sagent

Or run from a source checkout:

git clone --depth 1 https://github.com/rekursiv-ai/sagent.git
cd sagent
uv run sagent --help

Run

Bare sagent uses Anthropic and reads ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY=...
sagent

Pick a different provider by setting its key (see Provider setup) and passing --provider:

export OPENAI_API_KEY=...
sagent --provider OpenAI

--provider defaults to the first name in --allow-providers, so SAGENT_ALLOW_PROVIDERS alone picks the default backend and also caps which providers spawned sub-agents may use:

SAGENT_ALLOW_PROVIDERS=OpenAI sagent   # OpenAI is now the default provider

Pipe a prompt on stdin for non-interactive use:

printf 'Say hi in one sentence.' | \
  sagent --provider OpenAI --output-format json

Use --continue to resume the most recent session for this working directory, --session PATH for an explicit session directory, or --ephemeral when prompts and auto-memory should not be written to disk. Use --max-budget-usd N to cap API spend for the current run.

See CLI and Sessions for the full flag set.

Quickstart: Python

import asyncio

from sagent import tools
from sagent.agent import Agent
from sagent.lib.codec import immutable
from sagent.providers import Anthropic


async def main() -> None:
    agent = Agent(
        model=Anthropic.from_env().model("claude-sonnet-4-6"),
        system="You are a concise coding assistant.",
        tools=[tools.Read(), tools.Grep(), tools.Glob()],
    )
    result = await agent.run(immutable({"prompt": "Summarize README.md"}))
    print(result.content)


asyncio.run(main())

Agent.run() accepts a JSON directive with a prompt key and returns a Message.

See API, Tutorial, and Concepts for more detail.

Provider setup

Sagent ships API-key providers for Anthropic, OpenAI, OpenAISubscription, Google, Moonshot, DashScope, MiniMax, and generic OpenAI-compatible endpoints, a subscription-backed AnthropicCLI that rides your installed claude login, plus a managed local LlamaCpp provider. Set the key (or run the login) for the provider you plan to use:

export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GOOGLE_API_KEY=...
export MOONSHOT_API_KEY=...
export DASHSCOPE_API_KEY=...
export MINIMAX_API_KEY=...

and

export SAGENT_ALLOW_PROVIDERS=...

to set the default value of the --provider flag.

See Providers for the provider matrix, inference rules, and OpenAI-compatible provider setup.

Self-hosted models

Install the local runtime extra from a checkout:

uv sync --extra selfhosted

Or add it to your project from PyPI:

uv add "sagent[selfhosted]"

Then pass a HuggingFace repo ID or local snapshot path:

sagent --provider SelfHosted --model Qwen/Qwen3.6-27B+bfloat16+cuda
sagent --provider SelfHosted --model Qwen/Qwen3.6-27B+cuda+bfloat16

For a small smoke test:

sagent --provider SelfHosted --model Qwen/Qwen3-0.6B+float16+cuda \
  --effort none --max-response-tokens 32 --max-tool-call-rounds 1

SelfHosted options use + suffixes after the model name. Device, dtype, and compile can appear in any order, but each category can appear once.

The LlamaCpp provider is a second local option: it manages a llama-server subprocess and talks to it over its OpenAI-compatible endpoint. Point LLAMA_CPP_SERVER at a built llama-server binary and LLAMA_CPP_MODEL at a .gguf file, then run sagent --provider LlamaCpp --model qwen3.6-27b-12gb.

See Self-hosted Models for options, local snapshot paths, and runtime requirements.

Examples

The examples/ directory contains small, runnable examples:

• offline_custom_tool.py: run an agent/tool/model loop without API keys.
• decorator_tool.py: wrap a function as a tool.
• custom_tool.py: implement the full Tool protocol.
• multi_agent_reviewer.py: spawn an isolated reviewer child.
• openai_compatible_provider.py: connect an OpenAI-compatible endpoint.

Start with the tutorial, then use the examples as copyable patterns. See Examples and Tools.

Security and privacy

Sagent is an agent runtime, not a sandbox. Enabled tools run with the current process permissions: Bash executes local commands, file tools read and write accessible paths, and provider/network tools send data to their configured services. Sessions are plaintext local state and may contain prompts, model responses, tool results, file snippets, and paths.

Use narrow tool sets, pass --ephemeral for one-off sensitive prompts so sessions and auto-memory are disabled, and run Sagent inside your own OS/container sandbox when a task needs hard isolation. See Security.

Comparison

Name

sagent (noun, neologism) SAY-jent /ˈseɪ.dʒənt/

From sage + agent.

An AI assistant that confidently performs a task you didn't ask for while ignoring the one you did.

"I asked the sagent to fix one failing test -- it deleted the test and reported all green."

Contributing

See CONTRIBUTING.md for local validation and public contribution flow.

See also

Sibling projects in the rekursiv-ai family:

• trackinizer — Centralized agent database for tracking inquiries, work, and the evidence behind conclusions.
• wesearch — Web search, resilient page fetch, and scholarly-paper lookup without a browser stack.
• madcatter — Rich-based Markdown renderer for the terminal; ships the mdcat CLI.
• priml — Composable PyTorch building blocks: models, optimizers, losses, and a step-based training loop.
• configgle — Hierarchical experiment configuration in typed pure-Python dataclasses instead of YAML.
• copybarista — Bidirectional source sync for publishing OSS-ready trees from a monorepo.

Citing

If you find our work useful, please consider citing:

@misc{rekursivai2026sagent,
      title={Sagent - A coding-agent CLI and strongly-typed Python library -- self-mutating, hot-swapping, multi-provider, with async tool calls and bidirectional recursive spawn.},
      author={Joshua V. Dillon and Dan Kondratyuk},
      year={2026},
      howpublished={Github},
      url={https://github.com/rekursiv-ai/sagent},
}