English | 简体中文
A lightweight Python agent for one trusted user and one running instance.
tinyagent provides a command-line interface and an in-process Python SDK, with support for DeepSeek and custom OpenAI-compatible providers, persistent sessions, workspace tools, layered memory, MCP servers, and progressively loaded skills.
tinyagent requires Python 3.11 or later and currently targets Linux first.
Highlights
- One runtime, two interfaces: the CLI and Python SDK share the same async agent runtime.
- Provider flexibility: use DeepSeek out of the box or configure another OpenAI-compatible Chat Completions endpoint.
- Persistent work: sessions and complete message history are stored in SQLite outside the workspace.
- Workspace-aware tools: read, write, patch, list, and execute commands within a validated workspace boundary.
- Layered memory: combine compacted conversation context with curated, human-readable long-term memory.
- MCP integration: connect remote Streamable HTTP servers or local stdio servers through an explicit tool registry.
- Progressive skills: keep reusable instructions in
SKILL.md files and load their full content only when needed.
Quick start
Install uv, then install the project and initialize the current directory as a tinyagent workspace:
cd tinyagent
uv sync
uv run tinyagent init
init creates .tinyagent/config.toml, .tinyagent/workspace-id, and an empty skills/ directory. Provide API keys through the environment variable named in the provider configuration; never store credentials in the configuration file:
export DEEPSEEK_API_KEY="your-api-key"
Command execution on Linux requires Bubblewrap by default. If Bubblewrap is not installed or cannot run, tinyagent can detect the system, show the exact install command, and ask for confirmation before installing it:
uv run tinyagent sandbox install
Run diagnostics to verify the configuration, state store, memory, MCP servers, and command sandbox:
uv run tinyagent doctor
Start with a single turn:
uv run tinyagent run "Introduce yourself in one sentence."
Or open an interactive chat in a specific local workspace:
uv run tinyagent chat --workspace /tmp/tinyagent-test
Guided tour
Interactive chat
The chat interface supports persistent sessions, streaming Markdown, command completion, and multiline input:
/new [name] Create and switch to a new session
/sessions List sessions in the current workspace
/resume <id|name> Switch to an existing session
/help Show help
/exit Exit chat
Press Enter to send, Ctrl-J or Alt-Enter to insert a newline, and Ctrl-D to exit. Type / and press Tab to complete commands.
The default configuration lives at .tinyagent/config.toml in the workspace. A typical configuration looks like this:
[agent]
provider = "deepseek"
model = "deepseek-v4-flash"
context_window_tokens = 64000
max_tool_iterations = 50
max_tool_output_chars = 20000
[providers.deepseek]
base_url = "https://api.deepseek.com"
api_key_env = "DEEPSEEK_API_KEY"
request_timeout_seconds = 120
stream_idle_timeout_seconds = 30
max_retries = 2
retry_base_delay_seconds = 0.25
[tools]
enabled = true
read_only = false
allow_unsafe_exec = false
exec_network_access = true
max_file_bytes = 1048576
max_list_entries = 1000
exec_timeout_seconds = 60
max_exec_output_chars = 20000
[memory]
enabled = true
max_chars = 6000
curator_event_threshold = 10
[mcp]
To use another OpenAI-compatible service, add a provider section and set agent.provider to its name. tinyagent currently uses the Chat Completions API.
For read-only operation:
[tools]
read_only = true
Set enabled = false to disable the built-in workspace tools entirely. Only set allow_unsafe_exec = true when you explicitly accept execution without process-level filesystem isolation.
Sessions
Create, inspect, switch, and delete persistent sessions from the CLI:
uv run tinyagent sessions new project-a
uv run tinyagent sessions list
uv run tinyagent sessions resume project-a
uv run tinyagent run "Continue our previous discussion."
uv run tinyagent sessions delete project-a
You can also select a session for one command without changing the active session:
uv run tinyagent run "Remember the number 17." --session-id project-a
uv run tinyagent chat --session-id project-a
Memory
Inspect and manage long-term memory with:
uv run tinyagent memory show
uv run tinyagent memory sync
uv run tinyagent memory history --limit 20
uv run tinyagent memory restore 3
Long-term memory is stored as readable Markdown in .tinyagent/memory/MEMORY.md. After editing it manually, run memory sync to record a new revision.
MCP servers
Configure a remote Streamable HTTP server:
[mcp.servers.openai_docs]
transport = "streamable_http"
url = "https://developers.openai.com/mcp"
enabled_tools = ["search_openai_docs", "fetch_openai_doc"] # optional
connect_timeout_seconds = 30
tool_timeout_seconds = 60
allow_parallel_calls = false
Or configure a local stdio server:
[mcp.servers.local_index]
transport = "stdio"
command = "uvx"
args = ["local-index-mcp"]
cwd = "."
env = { CHILD_TOKEN = "LOCAL_INDEX_TOKEN" }
enabled_tools = ["*"]
Values in env and headers_from_env are the names of source environment variables, not credentials. After configuring a server, run uv run tinyagent doctor to inspect its connection and discovered tools.
Skills
Workspace skills live at skills/<name>/SKILL.md. A minimal skill looks like this:
---
name: release-notes
description: Produce concise release notes from the current changes.
---
# Release notes
Summarize user-visible behavior, compatibility changes, and verification.
List, validate, or inspect skills from the CLI:
uv run tinyagent skills list
uv run tinyagent skills validate
uv run tinyagent skills show release-notes
The model can load a relevant skill on demand. You can also activate one explicitly in a prompt:
Use $release-notes to prepare notes for this release.
Interfaces
CLI
Use uv run in a source checkout:
uv run tinyagent run "Hello"
uv run tinyagent chat
After installing the package, invoke the command directly:
tinyagent run "Hello"
tinyagent chat
Select another workspace with --workspace:
tinyagent doctor --workspace /path/to/workspace
tinyagent run "Summarize the current project." --workspace /path/to/workspace
Async Python SDK
The asynchronous API is the core interface:
import asyncio
from tinyagent import AsyncTinyAgent
async def main() -> None:
async with AsyncTinyAgent.from_config(workspace=".") as agent:
session = await agent.sessions.new("demo")
result = await agent.run("Hello", session_id=session.id)
print(result.content)
asyncio.run(main())
Stream events as they arrive:
async with AsyncTinyAgent.from_config(workspace=".") as agent:
async for event in agent.stream("Introduce this project."):
if event.type == "text.delta":
print(event.delta or "", end="", flush=True)
Synchronous Python SDK
from tinyagent import TinyAgent
with TinyAgent.from_config(workspace=".") as agent:
result = agent.run("Hello")
print(result.content)
Development
Runnable examples for each release are available in examples/:
uv run python examples/v0_7_demo.py
The standard development checks do not require provider credentials:
uv run ruff check src tests
uv run basedpyright
uv run pytest
Detailed design notes are available for each module:
License
This project is licensed under the terms in LICENSE.
tinyagent 是一个轻量级 Python AI 智能体，带有核心智能体循环，为单一可信用户和单一运行实例而构建，同时提供 CLI 和进程内 Python SDK。