agnoclaw

A small, embeddable, model-agnostic agent harness built on Agno.

agnoclaw combines Agno's model portability with an opinionated workspace, Agent Skills, policy and permission hooks, a transactional run lifecycle, scoped artifacts, and governed learning. It is a Python library first: no required gateway, editor, or hosted control plane.

0.13 release: Agno 3.0.6 is the default lock, with native large-result/media offloading, opt-in CodeMode, bounded normalized history, durable human-input continuation, and inert model-authored learning proposals. CodeMode is a trusted host-kernel interface; RuntimeBackend/LLMSandbox owns containment, and the operation ledger remains the durable effect authority. Agno 2.6.4 and 2.9.0 remain compatibility lanes. See the compatibility matrix for exact evidence and limitations.

Install

Python 3.11–3.14 is supported. The core is provider-neutral; install only the extras you use.

pip install agnoclaw                    # core; strings or an AgnoModelFactory
pip install "agnoclaw[anthropic]"       # recommended Claude setup
pip install "agnoclaw[local]"           # local Ollama
pip install "agnoclaw[cli]"             # CLI and async REPL
pip install "agnoclaw[postgres]"        # PostgreSQL runtime stores
pip install "agnoclaw[mcp]"             # MCP 2.0 deferred tool ingress
pip install "agnoclaw[server]"          # AgentOS + remote lifecycle HTTP edge
pip install "agnoclaw[code]"            # opt-in Agno 3 host-kernel CodeMode
pip install "agnoclaw[media-s3]"        # Agno 3 S3-compatible media offloading
pip install "agnoclaw[media-gcs]"       # Agno 3 Google Cloud media offloading
pip install "agnoclaw[full]"            # Claude + opt-in host CodeMode + web/scheduler/TUI

Run an agent

The default model is Claude, so this example requires ANTHROPIC_API_KEY and the anthropic extra.

from agnoclaw import AgentHarness

harness = AgentHarness()
result = harness.run("Summarize the files in this directory")
print(result.content)

Use any Agno-supported model with "provider:model_id":

harness = AgentHarness("openai:gpt-4o")
harness = AgentHarness("google:gemini-2.0-flash")
harness = AgentHarness("ollama:qwen3:8b")  # local; Ollama must be running

Choose runtime semantics

The preview exposes quick, durable, and service profiles; the no-argument legacy default remains only for migration compatibility. Start new short-running work with HarnessConfig.quick() or AgentHarness(profile="quick"). Durable/service construction requires explicit runtime and artifact stores; service additionally requires PostgreSQL runtime and Agno storage. See configuration reference.

For streaming compatibility:

async for event in harness.arun(
    "Analyze this repository",
    stream=True,
    stream_events=True,
):
    print(event)

Read the getting-started tutorial for provider setup, trusted execution context, sessions, cleanup, and expected failure behavior.

Control a run

start() returns the preview lifecycle facade without waiting for completion:

run = await harness.start(
    "Investigate the incident",
    session_id="incident-42",
    idempotency_key="incident-42:v1",
)
async for event in run.events():
    print(event.sequence, event.event_type)
result = await run.wait()
await harness.aclose(policy="drain")

If Agno pauses a durable run for confirmation, user input, feedback, or an external execution result, wait() raises RunInputRequiredError. Inspect the bounded request and continue it from the same or a reattached harness:

from agnoclaw import Respond, RunInputRequiredError

try:
    result = await run.wait()
except RunInputRequiredError:
    pending = await run.pending_requirements()
    await run.command(Respond(pending[0].request_id, {"name": "Ada"}))
    result = await run.wait()

The lifecycle persists intent, state, terminal results, and content-minimized normalized trajectory through a RuntimeStore; ambiguous outcomes are never blindly retried. Recovery continues from settled pre-model/result/evidence boundaries; exact-owner startup and reconciliation scans do not promise general mid-model restart. See run lifecycle, operations and recovery, and artifacts.

With a durable artifact store, start(..., persist_output=True) uses bounded provider streaming and run.output() replays authorized text segments by cursor. Authenticated remote starts default it to true. The final wait() result remains authoritative; replay does not imply an interrupted provider call is safe to resume.

Embed with trusted identity

Resolve identity in the host, then pass one immutable context to the harness:

from agnoclaw import AgentHarness, ExecutionContext

harness = AgentHarness(
    workspace_dir="/srv/agent/workspace",
    permission_mode="default",
    permission_require_approver=True,
)
context = ExecutionContext.create(
    tenant_id="acme",
    user_id="user-42",
    session_id="case-7",
    workspace_id="support",
    roles=["analyst"],
    scopes=["agents.run"],
)
result = await harness.arun("Continue the case", context=context)

The effect-safe model/capability slice can overlap through isolated Agno Agents. Local built-ins get fresh run-owned tools but remain typed single-flight with custom/streaming paths. Read the embedding guide before service deployment.

Use Agno learning safely

Learning is intent- and scope-driven. Personal/session stores can write directly with explicit consent; institutional observations become governed candidates first.

from agnoclaw import AgentHarness, LearningProfile

harness = AgentHarness(
    learning=LearningProfile.personal_and_session(
        user_profile="always",
        user_memory="agentic",
        session_context="always",
        max_updates_per_run=5,
    )
)
result = await harness.arun(
    "Remember that I prefer concise incident summaries",
    context=context,
    learning_consent=True,
)

With reviewed Learned Knowledge enabled, the model may call propose_learning under the policy's per-run update budget. The call only creates an inert candidate; an independent evaluator and authorized host must still promote it before future recall.

Scoped read/replace/forget administration is post-verified. Candidate capture, evaluation, promotion/rollback, unknown-effect discovery, evidence-bound reconciliation, and the leased/fenced maintenance worker are implemented on SQLite and PostgreSQL. Automatic promotion remains off pending custom-backend observers, production worker certification, deletion proof, and model-backed no-learning benefit. Start with learning, administration, and governed candidates.

Skills, workspace, tools, and backends

• Workspace instructions and memory are plain Markdown with explicit size limits and precedence. See workspace files.
• Agent Skills are loaded progressively and carry trust/tool restrictions. See the SKILL.md reference.
• Built-in shell, file, skill, and browser execution share one injectable runtime backend. See runtime backends.
• Capabilities use immutable descriptors and an operation-gated executor. Specs passed through AgentHarness(capabilities=[...]) receive version-pinned Agno binding, policy, durable approval-before-effect, active-lease fencing, and governed replay. Raw tools= are normalized as opaque, remain serialized only on named-legacy run/arun, and are rejected by start() and explicit-profile convenience calls until converted to explicit specs. See capabilities.

result = await harness.arun("Review the authentication module", skill="code-review")
print(result.content)

CLI

agnoclaw init
agnoclaw chat
agnoclaw run "Review src/" --skill code-review
agnoclaw tui
agnoclaw heartbeat start
agnoclaw migrate 0.12 service --help
agnoclaw schedule worker --runtime-db ~/.agnoclaw/runtime.db

Install the relevant extra first. The CLI reference records command groups, automation limits, and current durability boundaries; the configuration reference covers TOML, environment variables, and safe service defaults. Use durable scheduling for unattended jobs; JSON remains compatibility-only. The PostgreSQL migration lifecycle needs cli,postgres,scheduler; production certification remains open.

Why this shape

• Tiny public grammar: run, arun, start, get_run, session, and typed run controls instead of a second orchestration framework.
• Short and long work, one kernel: quick calls avoid unnecessary machinery while controllable work gains identity, intent, state, events, effects, and artifacts.
• Truth before retries: external effects have durable intent and explicit unknown outcomes; exactly-once external execution is never implied.
• Learning is a governed data plane: consent, scope, provenance, candidates, evaluation, reversible promotion, and deletion are separate concerns.
• Progressive power: local defaults stay approachable; service guarantees are enabled only with the stores, policy, and evidence they require.

The architecture and declared child-run contract cover host, model-visible DeclaredChildTemplate, and authenticated remote delegation. Competitive decisions are in World-class strategy, the Agno release audit, and the Lilian Weng research audit.

Compatibility and quality

The development lock is Agno 3.0.6; 2.6.4 remains legacy and 2.9.0 stable-v2. Schema-v12 is current. Token-free contracts and deterministic restart probes certify all three boundaries; real-service, chaos, soak, provider-backed, and hosted-CI gates remain separate.

• Compatibility matrix
• Evaluation and release gates
• Migration to 0.12
• Changelog

Documentation

Use the documentation index for tutorials, how-to guides, reference, explanations, operations, research, and release planning. HarnessAgent remains a backward-compatible alias for AgentHarness.

Development

uv sync --extra dev
uv run ruff check src/ tests/ scripts/

See CONTRIBUTING.md, support, security, and DEVELOPMENT.md.

License

MIT — fork it, inspect it, and embed it.