autoagent MCP server
Commit Nov 14, 2026A minimal, auditable LLM agent runtime for Python that provides tool use, sandboxed execution, and safety rails without the overhead of a framework.
Also known as laazizi/autoagent
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is autoagent MCP?
autoagent is a minimal, auditable LLM agent runtime for Python that provides tool use, sandboxed execution, and safety rails without the overhead of a framework.
Summary generated from the project's README
About autoagent MCP server
Python developers building LLM agents can use autoagent to implement a minimal, auditable agent loop without the complexity of a heavy framework. It provides a core library for managing the interaction between models and tools, focusing on transparency by keeping the entire execution loop in a single, readable file. The system supports multiple providers including OpenAI, Anthropic, DeepSeek, and Gemini, as well as any OpenAI-compatible endpoint like Ollama or vLLM.
Security is handled through code-based boundaries rather than prompts. Users can manage file access via ProjectWorkspace, execute dynamic tools in a Docker sandbox, and implement human approval workflows through a tool policy. The library includes advanced memory protocols like FactMemory for managing atomic facts and SummarizingMemory for long-term context. It also features an MCPClient to mount any MCP server tools directly into the agent environment with schema validation and pinning capabilities.
What you can do with it
- 1Securely execute agent-generated codeRun tools created by the LLM within a protected environment to prevent unauthorized system access.
- 2Integrate external MCP toolsMount tools from any MCP server as native agent tools using stdio transport.
- 3Implement human-in-the-loop approvalsPause agent execution to require manual verification before a sensitive tool is called.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
GEMINI_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelaazizi/autoagent is public and reachablegithub.com/laazizi/autoagent ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/laazizi/autoagent ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubautoagent
A minimal, auditable LLM agent core for Python. Not a framework.
autoagent is a small library that gives you the agent loop — LLM ↔ tools, done right —
and the safety rails around it, without pulling in a framework's worldview. The loop lives
in one file you can read end to end, and every boundary your agent has is Python code you
wrote, not a prompt you hope it respects.
from autoagent import Agent
agent = Agent.from_model("gemini", "gemini-3.5-flash")
@agent.tool
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
result = agent.run("What is 21 + 21?")
print(result.output) # "42"
That's the whole API for the common case. The JSON schema for add is generated from the
type annotations. The loop, retries, and provider wire formats are handled for you.
Prefer assembling visually? Try the visual builder online —
drag blocks (agent, tools, memory, MCP, checkpoint…), get runnable Python. Emit either a
standalone script or a build_agent() function to import into your own app. Fully offline,
also ships in the repo as constructeur_autoagent.html — and is tested headlessly: every preset
is generated in CI and checked to compile against the current library, and the page must declare
the library version it covers (tests/test_constructeur.py). A diagnostic strip tells you what
your assembly ignores or handles (approval, audit) before you copy anything.
Need live output? Streaming is a plain sync iterator — no async ceremony:
for ev in agent.run_stream("What is 21 + 21?"):
if ev.type == "text":
print(ev.text, end="", flush=True) # token deltas as they arrive
elif ev.type == "tool_start":
print(f"\n[calling {ev.tool_name}…]")
Why another agent library?
Because most of them are frameworks: they want to own your prompts, your memory, your control flow, and your dependency tree. When something misbehaves at 2 a.m., you're reading someone else's abstraction stack instead of your own code.
autoagent's theses:
- The agent must be readable. One loop, in one file — plain Python, no metaclasses,
no callbacks-on-callbacks, no YAML. You can follow a run from prompt to tool call to
answer without leaving
agent.py. - Bounding is code, not prompts. File access goes through
ProjectWorkspace(allowlists, anti path-traversal, write history + rollback). Generated tools run in a sandbox (Docker isolation when available, hardened AST denylist otherwise) and are promoted to native only through a hash-based manifest a human approves. - Zero dependencies for the core. Python ≥ 3.10,
http.client,dataclasses. No SDKs — each provider adapter speaks the wire format directly (~100 lines each), over one persistent connection per host (one TLS handshake per run, not per call). - Multi-provider without ceremony. OpenAI, Anthropic, DeepSeek, Gemini — plus any
OpenAI-compatible endpoint (Kimi/Moonshot, Groq, Ollama, vLLM…) via
ModelConfig(base_url=…). A provider is one method:complete(LLMRequest) -> LLMResponse. Write your own in 50 lines. - Synchronous and deterministic — with real streaming. The loop is sync by design —
you choose your concurrency model (
threading,asyncio.to_thread, a queue). No colored functions imposed on your codebase. Streaming is a plain sync iterator:for event in agent.run_stream(prompt): …yields text deltas and tool events as they happen (SSE under the hood, all four providers).
What's in the box
| Capability | What it gives you |
|---|---|
| Tool schema autogen | @agent.tool reads annotations + docstring → strict JSON schema (Literal → enums, additionalProperties: false by default) |
ProjectWorkspace |
bounded reads/writes: extension allowlists, anti path-traversal, change history, rollback |
| Dynamic tools + sandbox | the agent can write its own tools; they run in Docker (or a hardened subprocess), never natively without human promotion via a hash manifest |
TraceEmitter |
typed lifecycle events (run_start, tool_call_*, run_end…) with span/parent IDs → JSONL and/or callback; secret redaction built in (Bearer tokens, API keys never hit your logs) |
| Streaming | run_stream() / run_messages_stream() yield StreamEvents (text deltas, tool_start/tool_end, corrections) as plain sync iterators — SSE wire streaming in all four providers |
Memory protocol |
two methods (compact, recall) — duck-typed, @runtime_checkable. Built-ins: BufferMemory (hard cap), SummarizingMemory (old turns folded into an incremental LLM summary), and FactMemory (atomic facts kept up to date via add/update/delete consolidation — a contradiction replaces the stale fact; human-readable JSON store per identity; sleep-time consolidation with background=True — compact() returns in <1 ms, transcript folded only after facts are saved; semantic recall with any host embed_fn — lazy batch embeddings, sidecar file, lexical fallback). register_recall_tool() / register_remember_tool() let the agent read AND write its memory as tools |
RoutingProvider |
per-request dispatch across providers: text-only turns go to a cheap model, turns carrying images route to a vision-capable one — behind the standard provider interface, invisible to Agent |
post_turn_hook |
host-side verification loop: inspect what the agent did, inject a correction message, hard-capped iterations — validation in code, not vibes |
cancel_token |
cooperative cancellation (threading.Event), read between turns, between the chunks of a stream, before each tool that has not started (it does not run) and at the step boundary; forwarded to sub-agents (as_tool, delegate_to) |
| Multimodal | ImageAttachment on messages, serialized per provider |
agent.as_tool() |
the minimal multi-agent primitive: expose an agent as a tool of another (supervisor/specialist in two lines); stateless delegation, failures surface as tool errors, delegation cost (tokens, steps) reported to the parent |
Bounds |
the eight bounds (max_steps, token_budget, max_tool_result_chars, prune_tool_results_after, prune_batch, max_repeated_tool_calls, trifecta_guard, shadow_guards) as one readable, shareable, serialisable object — Agent(provider, bounds=PROD); agent.bounds.to_dict() into a trace. Every keyword still works |
token_budget |
hard cap on a run's cumulative token usage (TokenBudgetExceeded); per-call TokenUsage on results and done events — never invented, only what the provider reports |
parallel_tool_calls |
opt-in: multiple tool calls in one turn execute on a thread pool (I/O-bound latency win), transcript order stays deterministic |
Orchestrator |
for host-driven flows (guided forms, CATI questionnaires): your state machine decides every step; the LLM only interprets answers and rephrases prompts |
MCPClient |
mount any MCP server's tools as ordinary agent tools (stdio transport, zero dependencies): mcp.mount(agent, prefix=, include=) — server schemas validated by the registry before every call. Pin the definitions you reviewed (mcp.pin_tools("mcp_pins.json"), then mount(..., pins="mcp_pins.json")): a description or schema the server changes later ("rug pull") refuses the whole mount (0.26.0) |
OTelTraceExporter |
the trace tree becomes real OpenTelemetry spans (agent.run → llm → tool.<name>) for Jaeger / Tempo / Langfuse / Phoenix; opentelemetry-api is an optional extra, the core stays dependency-free |
RunState + resume |
durable runs: a JSON checkpoint after every completed step; resume after a crash, a restart, or past a raised max_steps / token_budget (exc.state is ready to resume) |
tool_policy |
one hook for allow / deny / human approval / quota-audit, checked for every tool call before any side effect; a crashing policy denies (fail-closed); ApprovalRequired pauses the run with a resumable snapshot |
| Taint tracking | mark a tool's output untrusted (@agent.tool(untrusted=True), mcp.mount(untrusted=True)) → its result is framed as data-not-instructions and the run is tainted; tool_policy sees ctx.tainted and can gate sensitive tools acting on externally-sourced content — indirect prompt-injection defense as testable code, not a probabilistic filter |
| Record / replay | RecordSession freezes a real run into a JSONL fixture; ReplaySession replays it deterministically — full-offline (zero network, zero tool side effects: any real run becomes a free CI regression test, no API key) or LLM-only (tools re-run, for debugging). A behavior change raises ReplayMismatch at the exact step. Pure wrappers, zero core change |
| Bi-temporal facts | A contradiction CLOSES the old fact's validity window instead of overwriting its text, so a botched extraction can no longer destroy a correct value and « since when? » has an answer (history(id)). Facts carry source (user statement vs agent inference), valid_from, invalid_at. A stale fact is never served as current — and facts() still returns only current facts, so consumers see what they always saw |
| Policy as data | ToolPolicySpec.from_dict({...}).compile() returns a callable with the existing tool_policy signature — so a policy becomes JSON you can version in git, read as a diff and test offline, without touching production code. Precedence is by action (deny > approve > allow), validation is strict at boot, and containment is monotonic: narrow() applies freely, expand() raises ApprovalRequired |
| Hybrid recall | FactMemory.recall() ranks with BM25 (IDF + length saturation, pure arithmetic — no dependency) and fuses it with cosine similarity via RRF when an embed_fn is present. The two signals fail on opposite queries: cosine loses exact matches (contract numbers, SIREN, plates), lexical loses synonyms. Stores without embeddings get the BM25 quality for free |
| Forgetting in plain language | forget_matching("forget everything about my previous employer") moves the decision to mutation time, which is where write-time-only memories fail: prefix collisions, compound facts, identifier variants. Returns the deleted facts as erasure proof; fail-closed (an LLM error or a malformed answer deletes nothing); the exposed tool is a dry run by default |
| Reliability, measured | autoagent.eval.run_k() reports pass^k, not just pass@1 — because pass^k ≈ p^k, a 90 % agent is a 43 % agent over 8 tasks (0.9^8). The judge is a deterministic host predicate, never an LLM: judging agent failures with an LLM is still weak — on the Who&When benchmark the best automated method named the responsible agent 53.5 % of the time and the failing step 14.2 % (Zhang et al., arXiv:2505.00212) |
| Prompt caching, measured | An agent resends the whole transcript every turn — the system prompt and every tool schema go out again at each step. TokenUsage.cached_tokens and cache_hit_ratio report the share the provider served from its cache, normalised across the four wire shapes (Anthropic counts it beside the input, everyone else inside it). ModelConfig(cache_prompt=True) adds the explicit marker Anthropic alone requires. The others cache on their own, and behaviour differs per provider — measure it: Gemini was opportunistic (the same 7 026-token prefix was served from cache on one call and not the next; a 9 366-token prefix missed where a 14 046-token one hit), DeepSeek was deterministic (measured zero on call 1, then 7 552 / 7 571 = 100 %). Report the saving as observed; never promise it |
| Context bounds | max_tool_result_chars truncates an oversized tool result middle-out (head keeps the payload's shape, tail keeps the totals and the trailing CRITICAL) with a marker that tells the model to narrow its query — one unbounded tool otherwise blows the context window and burns the whole budget. The marker counts against the bound: a bound that can be exceeded is not a bound |
| Context lifetime | prune_tool_results_after=N bounds how LONG a tool result stays in the transcript, not just how wide it is. Everything is re-sent at every step, and the history is never in the provider's cached prefix, so a 3 000-character result read at step 1 is paid again at steps 2, 3, 4… Past the N most recent, a result keeps its role and tool_call_id — the conversation stays well-formed — and loses only its payload, in the view sent to the provider: the returned transcript, the trace and any checkpoint keep the full text. Measured on demo 28: 16 360 → 7 592 input tokens (−54 %), same answer. The marker states the result was VALID, or the model re-plans around a failure that never happened; untrusted framing is carried over, so pruning can never un-taint a run. prune_batch=K prunes in batches so the view stays byte-stable between batches and the provider's prompt cache is not broken every turn — at the price of delayed pruning, stated in the demo |
| Parallel delegation | delegate_to({"comptage": a, "juridique": b}) registers ONE tool the model calls with a list of requests; those aimed at different specialists run concurrently. Measured on demo 29 against a real provider: 14.3 s -> 8.8 s, 39 % less wall clock, one tool call instead of three. It parallelises without going asynchronous — the call returns only once every specialist has finished, which is what keeps token_budget exact: with sub-agents in flight the cap would bound only what has landed, and the missing figure would not exist yet. Same specialist = serialised (an Agent serves one caller at a time); responses come back in REQUEST order, so the transcript stays replayable; a specialist that saw untrusted content returns framed output, so delegation cannot launder taint |
synthesize_tool() |
program synthesis by example, bounded: you bring Example(args, expected) truth, the model writes a tool, the sandbox runs YOUR cases and decides. Examples are split and the held-out ones never reach the model — not even when they fail — so "pass these cases" becomes "find the rule" instead of an if per example. Demo 31 against a real provider: accepted at attempt 1, 6/6 shown + 4/4 hidden, correct on a never-seen line. Rejected tools are deleted; accepted ones enter the hash-manifest promotion path. It does not make the model smarter — it converts attempts into correctness where truth is already known |
| Code as action, one line | agent.enable_code_action(): the model writes one short program that calls the agent's OWN tools (context['call_host']), and only what the program returns comes back into the conversation — a 26 000-character CSV stays in the sandbox, the model reads the sum. Each tool goes through the REGISTRY: argument validation, host context, and the same ToolSpec for the gate, so an egress tool stays egress (wiring tool functions by hand into PythonRunner(host_functions=…) loses that flag — a test reproduces the send that then goes out). Sub-agents are never exposed (their spend would escape token_budget). Short tool description plus one system-prompt sentence (hint=True): without it, deepseek-chat read the large result itself THEN ran a program. Confirmed with compare_configs on the efficiency bench (evals/eval_efficacite.py, 20 tasks, alternated arms, deepseek-chat): −26 % tokens per attempt [−35 % ; −18 %], same latency, no success lost (57/60 → 59/60, not significant) — multi-step tasks −74 %, but small tasks cost more (+27 % to +95 %): enable it for agents whose tools return large results. Confirmed on gemini-3.7-flash with the same protocol: −60 % [−63 % ; −57 %], 60/60 → 60/60, but +13 % latency there. With no sandbox passed it runs kernel-confined where Linux allows it, in the plain SubprocessSandbox elsewhere — use DockerSandbox in production |
| Voice under the loop (Gemini Live) | Agent.from_model("gemini_live", "gemini-3.8-live"): the microphone streams through a stdlib WebSocket client (autoagent.ws, zero dependency), audio comes back through on_audio, and every tool the model asks for BY VOICE goes through the same loop, gate, guards and journal as a text agent — the provider is just one more provider, no second execution path. Built from what the real API did, not from its docs page (a documented setup field is refused; tool turns end with a stale turnComplete that would otherwise yield an empty answer after every tool). agent.run(GeminiLiveProvider.LISTEN) waits for the user without a time limit. Not yet measured end to end with a real microphone |
| Kernel confinement, without Docker | SubprocessSandbox(confine=Confinement()) (Linux x86_64; applied by default when the host chooses no sandbox — a tool without a file permission has no file, without network no network; a tool granted files without named directories runs as before, and says so): the runner applies Landlock and a seccomp filter BEFORE the tool's code, through ctypes — no dependency. Files outside an allowlist, the network, launching programs and other processes are refused by the kernel whatever the code writes; the host grants read= / write= directories, never the model. A bench written before the code runs 13 payloads WITHOUT the AST validator (read a private file, read another process's API key through /proc, write, chmod, TCP, UDP, launch /bin/sh, kill a process…): 13 succeed without it, 0 with it; twelve legitimate snippets return the same result either way. +5.5 to +5.8 ms per cold call, +0.14 ms on a warm worker. Refused, not degraded, where it cannot be applied (Windows, macOS, ARM64, kernels before 6.2). The kernel stays shared — as with Docker; memory and CPU belong to limits= |
| Provenance of generated tools | DynamicToolBuilder(persist=True) records, for each tool, whether the run that had it written had read untrusted content. A tool built in a tainted run — directly or by a sub-agent — is QUARANTINED: not reloaded, not callable outside the run that built it, ignored by approval.load_tools, until a human release()s it by exact sha256. descendants() lists what was built while it was visible (EvoMal: copies outlive the original) |
| Response-channel guard (opt-in) | Agent(output_guard="neutralize"): in a TAINTED run, a URL of the final answer must appear in the transcript or it is removed — an image only from trusted content, a link also cited from the page. Closes the zero-click image-URL leak (image_markdown: 1/1 → 0/1 on the injection bench), linear-time, never logs the URL. Off by default: no false-positive rate measured on a real model yet. Its twin for tool CALLS, Agent(url_guard="deny") (0.26.0): in a tainted run a tool argument carrying a URL that appears nowhere in the conversation is refused — READING https://host/p?d=SECRET exfiltrates like a send. With both, the route bench finds no open route |
| Provenance of data at rest | what a tainted run WRITES for later keeps its origin (0.27.0): a fact remembered after reading an untrusted page comes back labelled, apart from trusted facts (FactMemory(tainted_facts="label" | "taint")); a file written then is recorded and read back as unverified (ProjectWorkspace(tainted_files=…)); "taint" re-arms the guards on reading; trust() is the human validation. run_persistence_bench measures the two-step attack (Monday plants, Tuesday acts) |
| Internal JSON-Schema validator | autoagent/validation.py replaces jsonschema, so the core truly has zero runtime dependencies. Covers what the library generates plus what MCP servers and model-written schemas use; differential-tested against jsonschema on a corpus (that test caught True vs enum: [1] before release); same error messages the model already read |
| Tools run while the model talks | @agent.tool(idempotent=True): in streaming, a tool call is often complete long before the message ends; the loop launches idempotent tools the moment their tool_call chunk arrives (all three providers emit it) and the tool phase consumes the result instead of re-running. Demo 32, two 1.2 s lookups in one turn: 6.1 s → 4.3 s (−29 %), transcript byte-identical. Never without the flag (a side effect is never speculated), the same guards run before launch, exactly one execution |
Cost-normalised run_k |
ReliabilityReport reports tokens_per_success, cost_per_success(cost_fn) with a host-supplied tariff, and pass_hat_k_at_budget(n) — score at fixed expenditure, the way serious benchmarks report it. Failures are paid too and counted; nothing is invented (no usage → None) |
cascade() |
the cheap model first, the big one only if YOUR judge says no — routing after the call, on the result, with the same deterministic check contract as run_k; failed tiers are paid and counted. Demo 33 measures it against a real provider: over 5 runs of four tasks (gemini-3.5-flash-lite → gemini-3.7-flash, thinking tokens counted) the cascade spent 67 % to 89 % fewer tokens than the big model alone, with 0 to 2 escalations per run (an escalation pays two tiers). Tokens, not euros: the demo prints the price ratio below which the cascade wins in euros, and the small model's acceptance rate on YOUR tasks is what decides. A human approval pause propagates — the cascade never routes around tool_policy |
summarize_trace() |
efficiency read from the JSONL trace after the fact, nothing added to the run: redundant tool calls (same run, same tool, same args), refusals per guard, shadow observations, early launches, pruned chars, tokens per success with failures included. Runs rebuilt from span parentage. Demo 34 runs offline |
| One decision gate | tool_policy used to see DIRECT tool calls only; the model also acts through the code it writes (run_python, generated tools → host functions via the bridge), the call_host_function dispatcher and sub-agents. Proven on 0.22.0: a policy refusing envoyer_mail refused nothing when the same send came from a program the model wrote — one mail sent in each of three scenarios. ActionGate (autoagent/gate.py) is now the ONE decision for every path: host policy (ctx.source = tool / host_function / subagent), trifecta guard, taint — which now enters the program (an untrusted host function taints the run). Fail-closed; an approval request DENIES (a program cannot be paused mid-run); sub-agents inherit the parent's policy on request (as_tool(inherit_policy=True)). tests/test_gate.py analyses the source: tool_policy is called from one place and every host-function sink decides BEFORE it runs, so a new execution path fails a test instead of bypassing the policy. The sandbox stays the boundary. Demo 36 runs offline |
| Durable journal | a run resumes from a snapshot taken at the end of each step; if the process dies DURING a step — the mail already left, nothing written — the resume redoes the step and the mail goes out twice (the literature reports the same defect across agent frameworks: Khan, arXiv:2608.03836, a single-autho |
autoagent MCP questions
Is autoagent a framework?
No, it is a minimal, auditable LLM agent core and a small library that provides the agent loop and safety rails without a framework's worldview.
How does the agent handle tool security?
Generated tools run in a sandbox using Docker isolation or a hardened AST denylist, and they require human approval via a hash-based manifest to be promoted to native tools.
Does it support multiple LLM providers?
Yes, it supports OpenAI, Anthropic, DeepSeek, Gemini, and any OpenAI-compatible endpoint like Groq or Ollama.
