Selectools
Build, orchestrate, and deploy guarded multi-agent applications in plain Python.
- Source repo
- johnnichev/selectools
- Stars
- ★ 11
- Last updated
- 3d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Python backend team adding an OpenAI- or Anthropic-backed tool-calling assistant to an existing service, with traces, retries, budgets, and streaming output.
- Not a fit if
- Teams still on Python 3.9 that cannot upgrade their environment
- Users wanting zero-config setup without optional extras or external services
- Source review
- 65/100 · Some gaps
What does this agent do, and when should you use it?
Selectools is a Python 3.10+ AI-agent framework centered on Agent, AgentGraph, Pipeline, and pattern-agent interfaces. It supports OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama, and LiteLLMProvider, with fallback and cost-routing provider options. An agent run returns an AgentResult with content, parsed structured output, usage, and an execution trace, while astream() emits StreamChunk items followed by the final result. The framework includes tool calling, four-stage guardrails, JSONL audit logging, sessions and memory, hybrid RAG, MCP, and evaluation components. It can be embedded as a Python library, served with selectools serve agent.yaml, or exposed through the Starlette-based AgentAPI.
A developer gives Agent Python functions decorated with @tool, a Provider, and AgentConfig. Agent.run() or Agent.ask() calls the model, handles native tool calls, and can pass data through input, output, tool_args, and tool_results guardrails; it returns an AgentResult whose trace records model calls and tool execution. AgentGraph runs multiple agents through nodes and edges, while Pipeline, @step, parallel(), and branch() compose synchronous or asynchronous steps. RAGAgent can be created from a directory, and HybridSearcher combines BM25 with vector retrieval and optional reranking. selectools serve agent.yaml exposes HTTP and SSE streaming, while AgentAPI offers POST /v1/chat, session CRUD, and optional bearer authentication.
- A Python backend team adding an OpenAI- or Anthropic-backed tool-calling assistant to an existing service, with traces, retries, budgets, and streaming output.
- An application team that assigns planning, drafting, and review to separate agents and orchestrates them with
AgentGraph.chain()or an explicit directed graph. - An internal knowledge-assistant team that wants to answer over local documents using RAGAgent, vector stores, BM25, and fused semantic retrieval.
- A business workflow that exposes email, resource-creation, or destructive tools and needs ToolPolicy, approval callbacks, guardrails, and AuditLogger records around execution.
- An engineering team that needs to publish a Python agent as REST/SSE endpoints with session isolation, persistent session stores, or Starlette ASGI deployment.
How do you install or deploy this agent?
Run pip install selectools. The documented runtime is Python 3.10+. For hosted providers, put the relevant credential in a .env file at the project root, for example OPENAI_API_KEY=sk-...; ANTHROPIC_API_KEY and GEMINI_API_KEY are also documented. Install optional capabilities as needed, such as pip install selectools[rag], pip install selectools[observe], or pip install selectools[mcp].
How do you use this agent?
For a no-key first run, import Agent, AgentConfig, and tool from selectools, then import LocalProvider from selectools.providers.stubs. Define a function with @tool(description="..."), create Agent(tools=[your_tool], provider=LocalProvider(), config=AgentConfig(max_iterations=3)), call result = agent.ask("your request"), and read result.content. To use OpenAI, use OpenAIProvider and configure OPENAI_API_KEY. To deploy a YAML-defined agent, run selectools serve agent.yaml; AgentAPI(agent, auth_key="secret") wraps an agent as a Starlette ASGI application.
What are this agent's strengths and limitations?
- It expresses multi-agent graphs and step composition in Python through AgentGraph, Pipeline, and the
|operator, without requiring a dedicated DSL or compilation step. - Structured output has local validation plus native JSON Schema constraints for OpenAI/Azure and Gemini, with an explicit
structured_statusoutcome. - Its safety controls cover input, output, tool arguments, and tool results; AuditLogger can write privacy-controlled, rotating JSONL records.
- One framework covers six provider paths, failover, cost-based routing, and REST/SSE serving through AgentAPI.
- Python 3.10 is the minimum runtime; Python 3.9 users must pin
selectools<1.0or upgrade their environment. - Several capabilities require optional packages and external services, including RAG, Redis, PostgreSQL, Supabase, MongoDB, DynamoDB, MCP, and observability backends.
- Hosted providers require their corresponding credentials and network access; model features and native structured-output support differ by provider.
- RAG/embeddings, MCP, A2A, the evaluator catalog, unified memory, the scheduler, and newer backends remain marked beta and may continue evolving in 1.x.
How does this agent compare with similar options?
The repository compares Selectools with LangChain/LangGraph: it presents AgentGraph.chain(a, b, c).run(prompt) and @step with | for graphs and pipelines, alongside built-in evaluation and traces, where the comparison shows StateGraph/compile() and LCEL Runnable patterns for LangChain/LangGraph. Migration suitability still depends on an application's existing LangChain dependencies and required integrations.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Selectools This agent | 65 · Some gaps | Library / SDKFree + model costs | ★ 11 | 3d ago | Python | OpenAI API · Claude API |
| Octomind | 70 · Some gaps | CLIFreemium | ★ 557 | 1d ago | Rust | OpenAI API · Claude API |
| DSPy-Go | 49 · Major gaps | CLIFree + model costs | ★ 203 | 4d ago | Go | OpenAI API · Claude API |
| npcpy Agent Framework | 43 · Major gaps | Library / SDKFree + model costs | ★ 1.5k | 4d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: tool execution has approval mechanism (ToolConfig.require_approval), shell tool uses shell=False with shlex parsing, SSRF protection covers browser tools and webhook, audit logging and PII handling options exist. Deductions: rollback only mentions session stores and checkpoints, no explicit tool execution rollback; publisher identity unverified but not penalized.
Evidence shows: README and CHANGELOG descriptions are consistent, test files exist using FakeProvider, CI configured for multiple Python versions. Deductions: no dependency availability proof (e.g., lock file), failure messages only partially mentioned (e.g., GuardrailError with trace).
Evidence shows: README clearly targets developers, provides multiple build methods (single agent, graph, deploy), supports multiple providers, has environment fit (Python 3.10+, optional dependencies). Deductions: capability boundaries not fully explicit in README (e.g., beta module list), trigger precision (e.g., guardrail trigger conditions) not detailed in docs.
Evidence shows: README structure clear, install notes present (pip install), naming stability (@stable markers), examples and FAQ (examples directory), known limitations (e.g., beta modules), Apache-2.0 license, versioning changelog (CHANGELOG.md), maintenance responsibility (NichevLabs contact). Deductions: no major deductions, but install notes do not cover all optional dependency installation methods.
Evidence shows: output usability high (structured AgentResult), marginal value clear (multi-agent, RAG, guardrails), cost-benefit has cost tracking feature. Deductions: cost-benefit lacks actual benchmark data, only mentions performance benchmark docs.
Evidence shows: README claims (e.g., test counts, model counts) partially corroborated in CHANGELOG and pyproject, but no independent verification. Deductions: facts and inferences not clearly separated, e.g., '50 evaluators' not directly verified in source.
- Publisher identity unverified; exercise caution regarding supply chain risks.
- Dependency version ranges are broad; consider using lock files for reproducibility.
- Some security features (e.g., guardrails) rely on heuristic patterns and may be bypassed.
- Rollback capability is limited; tool execution side effects may not be fully reversible.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.4.0 v1.4.0 — StreamEnd, Provider State & New SDK Majors
Release notes excerpt
Streamed turns now report usage and can carry opaque provider state for verbatim replay (#182); temperature becomes optional for reasoning models; and the supported SDK ranges widen to openai 2.x/3.x and anthropic 1.x. Added - **StreamEnd: usage and provider state at the end of a native stream (#182).** Providers may yield one selectools.types.StreamEnd as the last item of stream() / astream(). Its usage is counted into agent.usage, passed to on_llm_end / on_usage, and recorded on the LLM_CALL trace …View on GitHub ↗ -
v1.3.0 v1.3.0 — Streaming Contracts
Release notes excerpt
Makes final_turn_only structured output safe to rely on across upgrades (#174): behaviors that streaming chat integrators previously had to learn by reading the source are now documented, tested public contracts — enforced on every consumption surface: astream() chunks, the stream_handler callback in run()/arun(), and the selectools.serve SSE stream. The contract tests (tests/agent/test_structured_streaming_contract.py) pin every clause, so a refactor that breaks integrators breaks CI. The streaming contract …View on GitHub ↗ -
v1.2.0 v1.2.0 — Tool-Boundary Guardrails Complete & Structured Synthesis Follow-ups
Release notes excerpt
Second 1.x minor, closing the loop on v1.1.0's guardrail and structured-output work from real tool-heavy agentic chat usage (#164–#167). All additive; the frozen 1.0 API is unchanged. Every feature went through a high-effort adversarial multi-agent review before merge — 28 verified findings fixed with red-first regression tests. Tool-results guardrails (#165 → #168) tool_args (v1.1) gated what goes INTO a tool; tool_results gates what comes OUT — external API responses, retrieved RAG chunks, oversized blobs — before it re-enters the model context: ```python config = AgentConfig( …View on GitHub ↗
FAQ
Can I use it without OpenAI?
How can I limit spend or runaway execution?
max_total_tokens, max_cost_usd, and iteration limits. RouterProvider can select model tiers by complexity, and tool-result compression is also available.Will it execute risky tools automatically?
Does it have a production serving boundary?
selectools serve agent.yaml supports HTTP and SSE, while AgentAPI can create a Starlette ASGI app with chat, streaming responses, session CRUD, and bearer authentication.