A Tour

The quickstart agent could answer and call a tool. This tour gives an agent what it needs before it is allowed to act: a policy that asks a person before a refund, a sandbox where its commands run, a budget checked before every model call — and the record of each.

About fifteen minutes and a few cents of model usage. Part 2 needs Docker running and pip install "omnicoreagent[docker]". Every output shown is what the code printed on one run. Yours will differ where the model decides: its wording, the commands it chooses, and the tokens and cost. What the runtime does will not: the run pauses at the refund, resumes after the approval, and stops before the budget is spent.

1. Ask a person before a refund

A policy decides, for every capability the agent has, whether to allow it, deny it, or ask a person. Start from a built-in profile and add one rule: refunds are asked about.

The built-in profiles. interactive-dev allows your local tools, the workspace, memory, skills, code mode and sandboxed commands; it asks before commands outside a sandbox, network access, package installs, MCP tools, sub-agents and background runs; and it denies reading raw secrets. permissive-dev, the default for an agent that sets nothing, allows sub-agents, background runs and the MCP servers you configure outright, and denies unsandboxed commands, host files, network access and package installs instead of asking. strict-production allows nothing but its own telemetry without a rule of yours. See the security model.

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry
from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

tools = ToolRegistry()

@tools.register_tool("lookup_order")
def lookup_order(order_id: str) -> dict:
    """Look an order up."""
    return {"order_id": order_id, "status": "delivered", "total": 42.0}

@tools.register_tool("issue_refund")
def issue_refund(order_id: str, amount: float) -> dict:
    """Refund an order."""
    return {"order_id": order_id, "refunded": amount}

policy = build_default_policy("interactive-dev")
policy.rules.ask.append(
    PolicyRule(
        rule_id="ask_before_refunds",
        effect=PolicyEffect.ASK,
        capability="tool.local.call",
        target={"tool_name": "issue_refund"},
    )
)

async def main():
    agent = OmniCoreAgent(
        name="support",
        system_instruction="You help with orders. Refund when the customer asks. Answer in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.6-terra"},
        local_tools=tools,
        agent_config={"governance_config": {"enabled": True, "policy": policy}},
    )
    result = await agent.run("Order 1042 arrived broken, please refund it in full.")
    print("status:", result["status"])

    # A run can pause more than once — once per call that needs a person.
    while result["status"] == "awaiting_approval":
        for approval in result["approvals"]:
            print("waiting on:", approval["tool_name"], approval["arguments"])
            await agent.resolve_approval(
                result["run_id"], approval["approval_id"], decision="approve", approver="alice"
            )
        result = await agent.resume(result["run_id"])
        print("status:", result["status"])
    print(result["response"])

    story = await agent.get_run_trajectory(result["run_id"])
    print("segments:", len(story["segments"]))
    for call in story["tool_calls"]:
        print(" ", call["tool_name"], "->", call["outcome"])

    await agent.cleanup()

asyncio.run(main())

status: awaiting_approval
waiting on: issue_refund {'order_id': '1042', 'amount': 42.0}
status: success
A full refund of $42.00 has been issued for order 1042.
segments: 2
  lookup_order -> success
  issue_refund -> success

What happened:

The run paused at the refund — status awaiting_approval — with the exact call it wanted to make. Nothing was refunded until someone decided.
resolve_approval recorded who decided. decision="deny" with a note sends the model the reason instead; arguments={...} approves an edited call.
resume continued the run where it stopped. It can happen minutes or days later, in another process, when the agent’s memory is a durable store — SQL, Redis or MongoDB — through memory_router. This example keeps it in memory, so here the run lives only as long as the process (durable runs).
A run can pause again after a resume — once for each call that needs a person — so approve in a loop until the status is no longer awaiting_approval. A session_id is optional; the run makes one.
The story of the run has a segment for each stretch between pauses — here two — and story["tool_calls"] lists every call with how it finally ended. Each segment’s own trajectory has the details, including the policy decision behind every call.

Over HTTP, OmniServe exposes the same flow: approvals, decisions and resume are endpoints.

2. Run commands in a sandbox

Turn on a sandbox provider and the agent gets an execute tool. Its commands run inside the sandbox, not on your machine, and the sandbox is not given your process’s keys and tokens.

import asyncio

from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="builder",
        system_instruction="Use the execute tool to run commands. Answer in plain text, without markdown.",
        model_config={"provider": "openai", "model": "gpt-5.6-terra"},
        agent_config={
            "governance_config": {
                "enabled": True,
                "profile": "interactive-dev",
                "sandbox_config": {"provider": "docker"},
            },
        },
    )
    result = await agent.run("Which Linux distribution and Python version does your sandbox have? Check, don't guess.")
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            for execution in call["executions"]:
                print("ran:", execution["command"], "| exit", execution["exit_code"], "| in", execution["sandbox_provider"])
    await agent.cleanup()

asyncio.run(main())

Debian GNU/Linux 13 (trixie), specifically Debian 13.7.
Python: 3.12.14 at /usr/local/bin/python3.
ran: ['sh', '-c', "printf 'OS release:\\n'; cat /etc/os-release; printf '\\nPython:\\n'; python3 --version; printf 'Python path:\\n'; command -v python3"] | exit 0 | in docker

Every command the agent ran, with its exit code and where it ran, is in the record. Docker, E2B, Modal, Daytona and Vercel sandboxes are one line of configuration each (sandbox providers).

3. Put a price on it

A budget caps what a run, a session, an agent or the whole application may spend. Before each model call, the runtime prices the call — the input it counts, and the output at model_config["max_tokens"] — and holds that amount. If the hold does not fit, the run waits for a person instead of making the call. Without max_tokens, a budgeted call is priced at 4,096 output tokens and held to them: an answer that reaches the limit ends the run with termination_reason length, so set max_tokens when answers are long. A provider that counts input tokens differently can still settle a little above the hold; the real cost is recorded either way. Here, a limit far too small:

import asyncio

from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="thrifty",
        system_instruction="You are a helpful assistant.",
        model_config={"provider": "openai", "model": "gpt-5.6-terra"},
        agent_config={
            "governance_config": {
                "enabled": True,
                "profile": "interactive-dev",
                "budgets": {"request": [{"meter": "model_cost_usd", "limit": 0.0001}]},
            },
        },
    )
    result = await agent.run("Write a haiku about budgets.")
    print("status:", result["status"])
    request = result["budget_request"]
    print("needs", request["needed"], "| limit", request["limit"], "| spent", request["used"])

    await agent.grant_budget(result["run_id"], approver="alice", note="one-off, for the tour")
    resumed = await agent.resume(result["run_id"])
    print("status:", resumed["status"])
    print(resumed["response"])
    await agent.cleanup()

asyncio.run(main())

status: awaiting_budget
needs 0.049888 | limit 0.0001 | spent 0.0
status: success
Budgets balance dreams
Coins whisper through careful hands
Future blooms on plans

The run stopped before spending anything and waited. grant_budget is a recorded, one-off exception with a name on it — the policy itself is unchanged — and resume carried on. To end the run instead, deny_budget. Without amount, a grant covers the shortfall of the one call that stopped: the run can stop again at its next call. To give it headroom, grant more, e.g. grant_budget(run_id, approver="alice", amount=0.50). A grant adds to what the budget allows; budget_status(run_id) shows each budget’s limit, what was granted, what is spent, and what remaining.

What you have now

An agent that can act, and a record that says what it did and why it was allowed to. From here:

Policy reference

Profiles, rules, targets, and what every capability means.

Durable runs

Pauses, crashes and resumes; budgets in full.

Execution

The execute tool, the workspace bridge, sandboxes that die.

Every run is evidence

Trajectories, outcomes, training records, exporters.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

A Tour

A Tour

1. Ask a person before a refund

2. Run commands in a sandbox

3. Put a price on it

What you have now

Policy reference

Durable runs

Execution

Every run is evidence

​A Tour

​1. Ask a person before a refund

​2. Run commands in a sandbox

​3. Put a price on it

​What you have now

Policy reference

Durable runs

Execution

Every run is evidence

A Tour

1. Ask a person before a refund

2. Run commands in a sandbox

3. Put a price on it

What you have now