nanny-sdk

Python SDK for Nanny — the enforcement primitive for autonomous AI agents.

@tool, @rule, and @agent decorators that enforce step limits, token budgets, tool allowlists, and custom rules per function call. Works with LangChain, CrewAI, or any Python agent framework.

pip install nanny-sdk

Full docs: docs.nanny.run

How it works

Nanny runs as a parent process via nanny run. The SDK decorators communicate with it at each tool call to check limits before the function body executes. Outside nanny run, every decorator is a no-op — zero overhead in development and CI.

# Governed — enforcement active
nanny run

# Passthrough — decorators silent, agent runs normally
python agent.py
uv run agent.py

@tool — declare a governed tool

from nanny_sdk import tool

@tool(tokens=10)
def fetch_page(url: str) -> str:
    import httpx
    return httpx.get(url).text

Before fetch_page runs, Nanny checks the allowlist, per-tool call limits, and charges 10 tokens against the budget. If any check fails, a NannyStop exception is raised and the function body never executes.

Async functions work identically:

@tool(tokens=10)
async def fetch_page(url: str) -> str:
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.text

instrument — automatic LLM token tracking

import nanny_sdk, openai

client = openai.OpenAI()
nanny_sdk.instrument(client)   # one line — done

Call once at startup. Every LLM completion response is intercepted and its token counts are reported to Nanny's budget automatically — no @tool decorator needed on the LLM call itself.

Supported: OpenAI, Groq, Together AI, Azure OpenAI, LiteLLM, Anthropic, Mistral, Google Gemini (google-genai), Cohere v2. No-op in passthrough mode.

@rule — enforce a custom policy

from nanny_sdk import rule

@rule("no_sensitive_files")
def block_sensitive(ctx) -> bool:
    path = ctx.last_tool_args.get("path", "")
    return ".env" not in path and "secret" not in path

Rules run before every @tool call. Return False to stop execution with RuleDenied. The ctx object exposes requested_tool, last_tool_args, and counters.

@agent — activate named limits for a scope

In a multi-agent system, each agent has a different role and a different risk profile. @agent activates the right named limit set when each role runs, then reverts automatically when it's done:

from nanny_sdk import agent

@agent("researcher")
def run_research_loop(query: str) -> str:
    ...

Activates [limits.researcher] from nanny.toml for the duration of the function. Limits revert on exit, including on exception. Each role runs under its own budget and tool allowlist — hitting the analysis ceiling does not affect the reporter, and the analysis agent cannot call the reporter's tools.

nanny.toml example

[runtime]
mode = "local"

[start]
cmd = "uv run agent.py"

[limits]
steps   = 50
tokens  = 200
timeout = 120000

[limits.researcher]
steps  = 30
tokens = 100

[tools]
allowed = ["fetch_page", "search"]

Stop reasons

When a limit is exceeded, a NannyStop exception is raised with one of these reasons:

Requirements

• Python 3.11+
• httpx (only runtime dependency)
• nanny CLI:
  • macOS: brew tap nanny-run/nanny && brew install nannyd
  • Linux: curl -fsSL https://install.nanny.run | sh
  • Windows: irm https://install.nanny.run/windows | iex

Links

• GitHub
• Documentation
• Changelog