🏯 Yagura

Safety-native AI agent framework. Define tools, Yagura handles the rest.

What is Yagura?

Yagura (櫓) is a Japanese watchtower — the castle's eyes and shield. This framework brings the same philosophy to AI agents: every tool invocation passes through a multi-layered safety assessment before execution. Safety is not an add-on. It's built into the execution loop.

Key Features

• 3-Layer DangerAssessor — Rule-based (zero cost, instant) → LLM assessment → Fallback LLM. 90% of operations assessed without any LLM call.
• Plan Confirmation with Auto-Execute — Configurable threshold: READ-only plans auto-execute, dangerous operations require user approval.
• Environment-Aware Safety — Same tool, different danger levels in LOCAL vs DOCKER vs SERVER. Automatic adjustment.
• Zero Built-in Tools — Pure infrastructure. What the agent does is 100% defined by you.
• Provider Pattern Everywhere — LLM, State Store, Logger, Auth, Transport, Confirmation — all swappable.
• Dynamic LLM Routing — Route confidential data to local LLM, general data to cloud API. Per-step, automatic.
• Streaming — 9 event types. Real-time plan progress via async iterator or WebSocket.
• OpenTelemetry — Opt-in tracing for every plan, step, and LLM call. Zero overhead when disabled.
• 26 Ecosystem Packages — 188+ pre-built tools for AWS, GCP, Azure, Slack, Google Workspace, Microsoft 365, Docker, Kubernetes, databases, and more.
• 5 Safety Presets + 7 Starter Templates — From development() to maximum_security(). From chatbot to enterprise FastAPI stack.

Install

pip install yagura-agent

Quick Start

import asyncio
from yagura import Agent, Config, Tool, DangerLevel
from yagura.llm import AnthropicProvider

def list_files(directory: str) -> list[str]:
    import os
    return os.listdir(directory)

agent = Agent(config=Config(
    planner_llm=AnthropicProvider(model="claude-sonnet-4-20250514")
))

agent.register_tool(Tool(
    name="list_files",
    description="List files in a directory",
    parameters={
        "type": "object",
        "properties": {
            "directory": {"type": "string", "description": "Path to directory"}
        },
        "required": ["directory"]
    },
    handler=list_files,
    danger_level=DangerLevel.READ,
))

response = asyncio.run(agent.run("What files are in my home directory?"))
print(response.plan)

10 lines to a working agent with full safety assessment.

Why Yagura?

Safety Presets

from yagura import Config
from yagura.presets import safety_presets

# One line to configure safety for your use case
config = Config(planner_llm=my_llm, **safety_presets.enterprise())

Ecosystem

pip install yagura-tools-common    # Shell, file ops, HTTP (13 tools)
pip install yagura-tools-aws       # S3, Lambda, SQS, Bedrock (12 tools)
pip install yagura-tools-google    # Gmail, Drive, Calendar, Sheets (15 tools)
pip install yagura-tools-slack     # Messages, channels, files (7 tools)
pip install yagura-tools-db        # PostgreSQL, MySQL, SQLite + NL→SQL (4 tools)
# ... and 21 more packages

Starter Templates

git clone https://github.com/sk-kouta-dev/yagura
cd yagura/starters/chatbot
pip install -r requirements.txt
python main.py

Architecture

User Input → Planner (LLM) → Plan
                                ↓
                          PlanExecutor
                           For each step:
                            ├─ DangerAssessor (3-layer)
                            ├─ User Confirmation (if needed)
                            └─ ToolExecutor → Result

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Apache 2.0 — see LICENSE for details.