Sagent AI Agent

sagent🪄

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

<p align="center"> <img alt="sagent logo" src="https://raw.githubusercontent.com/rekursiv-ai/sagent/main/assets/logo-custom.webp" width="180"> </p> <p align="center"> <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/tutorial.md">Tutorial</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/concepts.md">Concepts</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/providers.md">Providers</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/tools.md">Tools</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/cli.md">CLI</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/sessions.md">Sessions</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/security.md">Security</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/architecture.md">Architecture</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/api.md">API</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/streaming.md">Streaming</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/compaction.md">Compaction</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/selfhosted.md">Self-hosted</a> · <a href="https://github.com/rekursiv-ai/sagent/blob/main/docs/showcase.md">Showcase</a> </p>

Quick Start

uvx sagent@latest

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 based on 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 luna, 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.
   • PaperDetails walks citation graphs; PaperFetch fetches 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.

    • Typed session records keep whatever no field names in extra.

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 the session records are protocols and dataclasses you import, compose, and unit-test.
    • Passes strict: basedpyright, pyrefly, and ty.

Example:

from sagent.agent.agent import Agent
from sagent.providers.catalog import ModelCatalog
from sagent.tools.glob_tool import Glob
from sagent.tools.grep import Grep
from sagent.tools.read import Read

async with ModelCatalog() as catalog:
    async with Agent(
        model=catalog["google"]["gemini-pro-3.1"],
        system_prompt="You are a scientist.",
        tools=[Read(), Glob(), Grep()],
    ) as agent:
        print(await agent.send("analyze the CSV in ./data/"))

Install

uv tool install sagent && sagent
# Later: uv tool upgrade 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.

Provider	Env variable / Command
Anthropic	ANTHROPIC_API_KEY, or workload identity
AnthropicCLI	sagent login --provider acli
OpenAI	OPENAI_API_KEY, or workload identity
Google	GOOGLE_API_KEY
GoogleCLI	sagent login --provider gcli
Moonshot	MOONSHOT_API_KEY
DashScope	DASHSCOPE_API_KEY
MiniMax	MINIMAX_API_KEY
SelfHosted
LlamaCpp	LLAMA_CPP_MODEL + LLAMA_CPP_SERVER

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-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.agent.agent import Agent
from sagent.providers.catalog import ModelCatalog
from sagent.tools.mcp import McpSession, servers
from sagent.tools.read import Read

async with ModelCatalog() as catalog, McpSession(servers(Path.cwd())) as mcp:
    model = catalog["google"]["gemini-pro-3.1"]
    async with Agent(model=model, 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 no journal or memories are kept, and run Sagent inside your own OS/container sandbox when a task needs hard isolation. See Security.

Comparison

<details> <summary>How Sagent compares to aider, LangChain, Claude Code, Codex CLI, Gemini CLI, and other adjacent projects</summary>

Not yet in Sagent: LSP, native sandboxing, desktop UI, tree-sitter repo map, hosted service, browser automation.

This comparison focuses on the runtime shape rather than every feature of each project.

	Sagent	aider	LangChain	OpenClaw	Cline	Claude Code	Codex CLI	Gemini CLI	Flue	Pi	Attractor	npcsh
Python library	✅	🟡	✅	❌	❌	❌	❌	❌	❌	❌	❌	✅
Multi-provider	✅	✅	✅	✅	✅	❌	❌	❌	✅	✅	✅	✅
Context compaction	✅	🟡	🟡	❌	🟡	✅	✅	✅	❌	✅	✅	❌
User-initiated backend swap	✅	✅	❌	✅	✅	❌	❌	❌	❌	✅	❌	✅
Agent-initiated backend swap	✅	❌	🟡	❌	❌	❌	❌	❌	❌	❌	🟡	❌
Agent self-mutation	✅	❌	❌	❌	❌	❌	❌	❌	❌	🟡	❌	🟡
Context hot-swap	✅	🟡	🟡	🟡	🟡	❌	❌	❌	🟡	✅	✅	❌
Recursive agent spawn	✅	❌	✅	🟡	❌	🟡	🟡	❌	✅	🟡	✅	✅
Multi-agent (fully detached)	✅	❌	✅	✅	❌	🟡	🟡	❌	✅	🟡	✅	🟡
GitHub stars (May 2026)	--	44.4k	135.8k	368.6k	61.4k	--	80.1k	103.2k	2.5k	48.6k	1.1k	388

✅ = yes, 🟡 = partial, ❌ = no. Corrections welcome -- open a PR.

How each project works

• aider -- git-native pair programmer; markdown-diff edits (no structured tool calls), litellm transport, destructive mid-session /model swap, tree-sitter repo map, no multi-agent.
• LangChain/LangGraph -- broad LLM-app framework; everything is possible but application-defined, not an opinionated agent loop.
• OpenClaw -- TypeScript multi-platform personal assistant; multi-agent but end-user-oriented, no Python library.
• Cline -- VS Code extension; multi-provider, single-agent, truncation-based context, not importable.
• Claude Code (Anthropic) -- Anthropic-only vendor CLI; recursive sub-agents and compaction, but no provider swap and no Python library (JS SDK).
• Codex CLI (OpenAI) -- OpenAI-only Rust CLI; sandboxed local execution, single-agent, no compaction, no API.
• Gemini CLI (Google) -- Google-only TypeScript CLI; summarization compaction, single-agent, no API, no custom tools.
• Flue (Astro) -- headless TypeScript harness; pluggable sandboxes, recursive session.task() delegation, model chosen per call (no agent-initiated swap), no UI/compaction.
• Pi (earendil-works/pi) -- minimal TypeScript harness; branchable session tree, /reload soft self-mutation, sub-agents opt-in only.
• npcsh -- Python agentic shell; filesystem-defined NPC personas, many built-in modes, hub-and-spoke sub-agents, rate-limit-fallback "compaction".
• Attractor (StrongDM) -- a spec, not an implementation; DOT-graph pipeline where nodes are AI tasks and the graph is the workflow.

</details>

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