tinyagent README

The project's README from github.com/timczm/tinyagent. As one markdown file: README.md.

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

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:

License

This project is licensed under the terms in LICENSE.

tinyagent (timczm/tinyagent)

Searching Database…

253 ·GitHub
Tinyagent
Что это такое?tinyagent — лёгкий AI-агент на Python с базовым агентским циклом, созданный для одного доверенного пользователя и одного запущенного инстанса; он предлагает и CLI, и внутрипроцессный Python SDK.
Это CLI-инструмент или библиотека, которую я импортирую?И то и другое: это интерфейс командной строки и внутрипроцессный Python SDK с общим асинхронным агентским рантаймом, так что можно общаться в терминале или встроить его в собственный Python-код.
Как его запустить?Установите uv, установите проект, затем выполните init-команду, чтобы превратить текущий каталог в рабочее пространство tinyagent: создадутся .tinyagent/config.toml, файл workspace-id и каталог skills/.
Нужны ли Python и API-ключ определённого провайдера LLM?Да, требуется Python 3.11 или новее, а API-ключ вы передаёте через переменную окружения — по умолчанию для DeepSeek или любого другого OpenAI-совместимого эндпоинта Chat Completions.
В чём подвох с запуском shell-команд?Для выполнения команд на Linux по умолчанию нужен Bubblewrap для песочницы; если его нет, tinyagent может предложить его установить, а отключить песочницу можно, только явно задав allowunsafeexec, что убирает изоляцию файловой системы.
Работает ли он и на macOS или Windows?Сейчас он нацелен в первую очередь на Linux; README не подтверждает поддержку macOS или Windows.
Это десктоп-приложение или оно работает в терминале?Это терминальный CLI со стриминговым Markdown, автодополнением команд и многострочным вводом, плюс Python SDK для встраивания в скрипты.
Где хранятся мои сессии и история переписки?Сессии и полная история сообщений хранятся локально в SQLite вне каталога рабочего пространства.
Как устроена поддержка MCP-серверов?Можно подключать либо удалённые Streamable HTTP MCP-серверы, либо локальные stdio-серверы через явный реестр инструментов, а команда doctor позволяет осмотреть соединение и найденные инструменты.
Что такое система скиллов?Скиллы — это переиспользуемые инструкции в файлах SKILL.md внутри папки skills/ рабочего пространства; они загружаются постепенно, только когда модель решит, что они релевантны, или когда явно активированы в промпте.
Какая у него долговременная память?Он сочетает сжатый контекст беседы с отобранной человекочитаемой долговременной памятью, хранящейся как Markdown в .tinyagent/memory/MEMORY.md, — её можно править вручную, а затем синхронизировать.
Какие инструменты для рабочего пространства встроены?Инструменты, знающие о рабочем пространстве, позволяют агенту читать, писать, латать и перечислять файлы и выполнять команды, причём всё ограничено проверенным каталогом рабочего пространства ради безопасности.
What are similar projects?codeAgent, Baize, bareloop, brigade, Benzi, Proteus, Raven, claude-code
Which topics is it in?sandboxing, agent-memory, memory, openai-compatible, deepseek, sqlite, sdk, command-line, mcp-server, ai-agent, command-line-tool, agent
Creator
timczm
Size
0.3 MB
Stars
253
Updated
CommitAug 24
Age
1mo
Commits · 90 Days