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 · Self-hosted · Showcase

Quick Start

uvx sagent

See Install for additional details.

Features

1. Async runtime.

   • Commands auto-background when you type or when long-lived.
   • Consequence: Your agent always responds as fast as your service provider.
   • Tell a stuck task to stop, or detach one and let it keep running.

2. Hot self-mutation.

   • Conversationally change the model / service provider.
   • Conversationally have the model edit its own session.

3. Every Provider, every auth.

   • Anthropic, OpenAI, Google, Moonshot, DashScope, MiniMax, OpenAI-compatible endpoints, self-hosted HuggingFace models, and a managed llama.cpp server, all behind one binary.
   • Subscriptions supported and terms-of-service compliant.

4. Unified cost tracking.

   • One USD total across every provider in a session.
   • Pricing base don API costs when on sub.
   • Sub-agent costs roll up to the root. --max-budget-usd N caps the whole tree.

5. 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."

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

7. Richer built-in tools.

   • WebSearch/Fetch use headed or headless chrome.
   • PaperSearch/PaperFetch walk citation graphs and fetch PDFs.
   • Multi-backend WebSearch, WebFetch with markdown extraction, atomic read/write tracking on file tools.

8. 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).

9. Misaligned Bash tool calls are auto promoted to dedicated types.

   • Example: ls files/ is auto-promoted to List(files/) tool call.

10. Universal session format.

    • Convert claude/codex sessions to from sagent format and vice versa.

11. All spawns' sessions (ancestors and/or descendants) can be focused.

12. Send a message to parent to autocreate an autopiloting agent.

13. Apache 2 license.

Uniquely also an API

14. One runtime, every surface.

    • The same Agent class powers the CLI, your application code, and recursive sub-agents.

15. Typed Python objects.

    • Agent, Tool, Model, Provider, and Message are protocols and dataclasses you import, compose, and unit-test.
    • Passes strict: basedpyright, pyrefly, and ty.

Example:

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

uv tool install sagent && sagent

If you're missing uvx/uv,

• Mac

  brew install uv
  

• Linux

  sudo apt install -y curl
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

Optionally, for faster glob and grep,

• Mac

  brew install fd ripgrep
  

• Linux

  sudo apt install -y fd-find ripgrep
  

To 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

Authorization

Sagent supports all subscriptions and API KEYs.

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

Self-Hosted

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.

MCP

Sagent calls the tools of MCP servers. Manage them with sagent mcp, which takes the arguments claude mcp does; each command has --help, and each is also /mcp.COMMAND at the prompt:

sagent mcp add git -- uvx mcp-server-git                       # a local command
sagent mcp add -t http linear https://mcp.linear.app/mcp       # a remote URL
sagent mcp add -t http github https://api.githubcopilot.com/mcp/ \
  -H 'Authorization: Bearer ${GITHUB_TOKEN}'                   # read at connect
sagent mcp login linear    # OAuth sign-in to a remote server; --headless over ssh
sagent mcp list            # each server, and whether it connects
sagent mcp get linear      # one server
sagent mcp logout linear   # forget its sign-in
sagent mcp remove linear   # and the server

add writes this project's servers; -s user writes every project's. A session reads the servers it starts with; one already open keeps its own.

Each tool becomes mcp__<server>__<tool>. An on_demand server is one tool, mcp__<server>, that lists, describes, and runs its tools, so a large server costs no tokens until used. Its options beyond add's flags go in with add-json, as the entry another tool's mcpServers JSON holds:

sagent mcp add-json linear '{"url": "https://mcp.linear.app/mcp", "loading": "on_demand"}'

A remote server that signs users in with OAuth, as Linear and Notion do, needs one sign-in before it connects. One that takes a token instead, as GitHub's does, reads it from its header. Config copied from Claude Code, Cursor, or Pi works as it is: pass the file with --mcp-config PATH.

In code, open the servers and pass their tools:

from pathlib import Path

from sagent import tools
from sagent.agent import Agent
from sagent.providers import Google
from sagent.tools.mcp import McpSession, servers

model = Google.from_env().model("gemini-pro-3.1")
async with McpSession(servers(Path.cwd())) as mcp:
    async with Agent(model=model, tools=[tools.Read(), *mcp.tools()]) as agent:
        ...

See the sagent.tools.mcp docstring for every field.

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},
}