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.

Providers and tools

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:

• Core runtime
• Sessions
• Tool runtime and function calling
• Workspace tools
• Memory
• MCP
• Skills

License

This project is licensed under the terms in LICENSE.