kaze-agent-base

Reusable ADK-based agent infrastructure — plugin loader, background workflow engine, FastAPI server, memory service, LLM wrapper with trace propagation.

Extracted from kaze-agent-ops so other agents can be built on the same framework.

Install

pip install kaze-agent-base
# Optional extras:
pip install "kaze-agent-base[memory]"    # Mem0 + pgvector
pip install "kaze-agent-base[tracing]"   # Langfuse callbacks

Build your own agent

Your agent package owns:

• plugin.yaml + tools.py files under my_agent/plugins/<name>/
• config.yaml listing models and specialists
• A package __init__.py that builds the workflow
• An entrypoint script that calls create_app(...)

Directory layout

my_agent/
  pyproject.toml              # depends on kaze-agent-base
  config.yaml                 # model tiers, specialists
  my_agent/
    __init__.py               # builds workflow, exposes _workflow_*
    serve.py                  # calls create_app(...)
    plugins/
      root/plugin.yaml + prompt.md
      <specialist>/plugin.yaml + tools.py [+ workflows/]

my_agent/__init__.py

from pathlib import Path

from kaze.agent_base.workflow.graph import build_workflow

_PKG_ROOT = Path(__file__).parent

_workflow, _agents = build_workflow(
    config_path=_PKG_ROOT.parent / "config.yaml",
    plugins_root=_PKG_ROOT / "plugins",
    plugins_package="my_agent.plugins",
    workflow_name="my_agent",
    workflow_description="My agent — short tagline",
)

_workflow_agents = _agents
_workflow_config = _workflow._kaze_config
_workflow_mcp_toolsets = _workflow._kaze_mcp_toolsets

root_agent = _workflow
__all__ = ["root_agent"]

my_agent/serve.py

from pathlib import Path

from kaze.agent_base import create_app
from kaze.agent_base.server import run


def main():
    app, host, port = create_app(
        app_module="my_agent",
        agents_dir=Path(__file__).resolve().parents[1],
        title="My Agent API",
        description="…",
        version="0.1.0",
    )
    run(app, host, port)


if __name__ == "__main__":
    main()

Wire up a [project.scripts] entry (e.g., my-agent-serve = "my_agent.serve:main") and you have a deployable agent.

Environment variables

The KAZE_ prefix is historical; downstream agents can use the same prefix or layer on their own env vars.

Public API

from kaze.agent_base import (
    acompletion,           # LLM call with trace linkage
    set_trace_id,
    reset_trace_id,
    ToolAgent,             # ADK BaseAgent that runs a tool in a thread
    get_engine,            # background WorkflowEngine singleton
    spill,                 # persist large outputs to disk
    discover_plugins,
    get_workflow_templates,
    get_tool_registry,
    resolve_tools,
    create_app,            # FastAPI factory
)

Layout

src/kaze/agent_base/
  config.py                  load_config(path)
  models.py                  LiteLlm factory (gateway-routed)
  llm.py                     acompletion + trace propagation
  plugin.py                  discover_plugins(plugins_root, plugins_package)
  tool_registry.py           framework:* + <plugin>:* namespaces
  tools/                     background, memory, notify, system, code, bash, fs, artifacts
  jobs/                      engine, store, tool_agent (background workflows)
  state/                     memory (mem0), config_store, sessions, services
  server/                    app (create_app, run), routes, schemas
  workflow/                  graph, agents, callbacks, mcp

License

Apache-2.0