miniadk 0.1.0

A tiny Python agent runtime with tools, middleware, and events.

MiniADK

简体中文

MiniADK is a small Python Agent Development Kit for building tool-using agents with a compact, readable API.

It gives you the pieces needed to build agent products:

• Agent for instructions and capabilities
• Model adapters for LLM providers
• Tool wrappers for Python functions
• Runtime for the agent loop
• Event streams for adapters and UIs
• Session helpers for conversation state

MiniADK is a development kit, not a finished agent product. The core stays small, while providers, tools, policies, skills, MCP, CLI adapters, and presets live around it.

Install

Clone the source and install it in editable mode:

git clone https://github.com/Saglear/miniadk.git
cd miniadk
uv sync --extra dev

Run the test suite:

uv run --extra dev pytest -q

Quick Start

from miniadk import Agent, model, run_cli, tool


@tool
def add(left: int, right: int) -> int:
    """Add two numbers."""
    return left + right


agent = Agent(
    "calc",
    "Use tools when they help.",
    tools=[add],
)

run_cli(agent, model=model())

Run it:

uv run python calc.py

One-Shot Calls

from miniadk import Agent, model, run, tool


@tool
def greet(name: str) -> str:
    """Return a greeting."""
    return f"hello {name}"


agent = Agent("hello", "Use tools when useful.", tools=[greet])
answer = run(agent, "Greet Ada", model=model())
print(answer)

Models

model() reads provider settings from environment variables and returns a configured adapter.

OpenAI-compatible settings:

OPENAI_KEY=...
OPENAI_URL=...
OPENAI_BASE_URL=...
OPENAI_MODEL=...

Anthropic settings:

ANTHROPIC_KEY=...
ANTHROPIC_URL=...
ANTHROPIC_BASE_URL=...
ANTHROPIC_MODEL=...

When more than one provider is configured, choose the default explicitly:

MINIADK_MODEL_PROVIDER=openai

or:

MINIADK_MODEL_PROVIDER=anthropic

Tools

Any typed Python function can become a tool:

from pathlib import Path

from miniadk import tool


@tool
def read_note(path: str) -> str:
    """Read a UTF-8 note."""
    return Path(path).read_text(encoding="utf-8")

MiniADK uses the function name, docstring, and type hints to build the tool schema. Sync and async functions are both supported.

Prebuilt Tools

Reusable tools are available from miniadk.stdtools:

from pathlib import Path

from miniadk import Agent, model, run_cli
from miniadk.stdtools import make_list_files, make_read_file, make_search_text

root = Path.cwd()
agent = Agent(
    "repo",
    "Help inspect this repository.",
    tools=[
        make_list_files(root=root),
        make_read_file(root=root),
        make_search_text(root=root),
    ],
)

run_cli(agent, model=model())

File and shell tools keep path checks, permission prompts, limits, and timeouts outside the atomic runtime.

Skills And MCP

Skills and MCP servers are business-layer integrations. They resolve into ordinary instructions and tools before the runtime loop runs.

from miniadk import Agent, MCPHub, MCPServer, SkillRegistry, model, run_cli

agent = Agent(
    "assistant",
    "Use the configured project capabilities.",
    skills=SkillRegistry.from_paths(".miniadk/skills"),
    mcp=MCPHub([
        MCPServer(name="docs", command="uvx", args=["some-mcp-server"]),
    ]),
)

run_cli(agent, model=model())

Core Shape

The runtime loop is intentionally direct:

user message
  -> model call
  -> optional tool calls
  -> tool results
  -> model response
  -> events

The core concepts are:

Message  - what the agent sees
Model    - how the agent asks an LLM what to do next
Tool     - what the agent can do
Agent    - instructions plus capabilities
Runtime  - the loop that connects everything
Event    - what adapters and UIs observe
Session  - persisted conversation state

Package Layout

src/miniadk/core/       atomic runtime types and loop
src/miniadk/models/     provider adapters
src/miniadk/stdtools/   reusable file, shell, web, and agent tools
src/miniadk/adapters/   CLI, JSON, web, and WebSocket adapters
src/miniadk/skills.py   skill loading and invocation helpers
src/miniadk/mcp.py      MCP integration
src/miniadk/presets.py  optional high-level assembly helpers

Import the common user-facing API from miniadk. Use submodules when you need advanced control.

Examples

uv run --extra dev python examples/smoke_llm.py
uv run --extra dev python examples/scripted_tiny_product.py
uv run --extra dev python examples/coder_preset.py
uv run --extra dev python examples/compact_coder.py
uv run --extra dev python examples/repo_cli.py
uv run --extra dev python examples/cli_interaction_lab.py

Development

uv sync --extra dev
uv run --extra dev pytest -q
uv build

License

MIT