hajimi 0.1.1

Async-first Python agent framework with tools, skills, MCP, sessions, and tracing.

Hajimi Agent

Hajimi is a small async-first Python agent framework built around any-llm-sdk direct async APIs.

Core capabilities:

• TOML and .env based configuration.
• Loguru console and rotating file logging.
• Async completion, streaming completion, embedding, and Responses API wrappers.
• A typed core with message parts, stream events, context objects, and a compact agent loop with optional tool dispatch.
• Workspace read/search tools, opt-in write/shell tools, local skills with progressive activation, optional MCP tools, BM25 tool search, agent-as-tool subagents, and persistent in-process teammates.
• Durable AgentSession context with JSONL events, SQLAlchemy ORM indexes defaulting to SQLite, forks, edit/delete/restore markers, compaction, and token reports with optional provider cache usage.
• JSONL tracing with optional OpenTelemetry export.
• Pytest coverage for configuration, logging, LLM wrappers, tools, skills, MCP, sessions, tracing, subagents, teammates, workspace tools, and dynamic tool search.

Quick start:

uv sync
cp examples/configs/.env.example examples/configs/.env
export HAJIMI_API_KEY=...
export HAJIMI_BASE_URL=https://api.deepseek.com
export HAJIMI_MODEL=deepseek-chat
uv run hajimi chat "hi"
uv run python examples/basic_agent.py
uv run pytest -q

CLI:

hajimi chat "hi"
hajimi chat --json "hi"
hajimi agent models --json
hajimi tool list
hajimi mcp list
hajimi skill list

Examples:

uv run python examples/basic_agent.py
uv run python examples/stream.py
uv run python examples/tools.py
uv run python examples/custom_loop.py
uv run python examples/session.py
uv run python examples/routed_runtime.py
uv sync --extra mcp
uv run python examples/mcp_stdio.py

Minimal one-call usage (no TOML required):

# Export at least one provider key, e.g.:
#   export HAJIMI_API_KEY=...        # overrides the selected configured model
#   export HAJIMI_BASE_URL=...       # optional provider endpoint
#   export HAJIMI_MODEL=deepseek-chat   # optional model id override
#   export OPENAI_API_KEY=...        # auto-detected as the openai default
#   export DEEPSEEK_API_KEY=...      # auto-detected as the deepseek default
#   export HAJIMI_DEFAULT_MODEL=openai   # optional, when several keys are set
from hajimi import Hajimi
print(await Hajimi.ask("hello"))

Typed core API:

from hajimi import TextDelta, user_message

async with agent.run_stream([user_message("hello")]) as run:
    async for event in run:
        if isinstance(event, TextDelta):
            print(event.chunk, end="")

print(run.output)

Custom loop API:

from collections.abc import AsyncIterator

import hajimi as ai


class CustomAgent(ai.Agent):
    async def loop(self, context: ai.Context) -> AsyncIterator[ai.AgentEvent]:
        while context.keep_running():
            async with (
                ai.stream(context=context) as stream,
                ai.ToolRunner() as tools,
            ):
                async for event in ai.merge(stream, tools.events()):
                    yield event
                    if isinstance(event, ai.ToolEnd):
                        tools.schedule(context.resolve(event.tool_call))

                context.add(stream.message)
                context.add(tools.get_tool_message())

Power-user knobs travel on a single RunOptions object:

from hajimi import AgentRuntime, RunOptions, load_config

runtime = await AgentRuntime.from_config(await load_config())
result = await runtime.run_task(
    "draft a release note for v0.2",
    options=RunOptions(
        mode="auto",
        max_cost_usd=0.05,
        max_total_tokens=8000,
        on_budget_exceeded="stop",
    ),
)
print(result.content, result.cost)

Optional extras:

uv sync --extra mcp
uv sync --extra observability

Docs:

• Configuration
• Observability
• Context
• Skills
• MCP
• Multi-agent
• Research notes