RagLeap
Blog

How to build an AI agent that asks for approval before it acts (Python, ragleap-agents 0.5.1)

This post shows how to build a Python AI agent that stops and asks a human before it acts on the outside world, using ragleap-agents 0.5.1 (released 2026-11-14). Everything below comes from that version's README, release notes and changelog, checked on 2026-11-15. The code blocks are copied from the README at the tag. Status: Released library. It has not been independently security reviewed.

What is an approval gate in an AI agent?

An approval gate is a pause before an action that affects the outside world. In ragleap-agents the model proposes one action at a time, sees the result, and proposes the next, up to a hard step cap. When a tool needs approval, the run stops with the status awaiting_approval, a human decides, and the run resumes or the action is rejected.

How do I install ragleap-agents?

Run pip install ragleap-agents (or uv add ragleap-agents). You bring the model as a plain callable, or use the included adapter for OpenAI-compatible chat APIs. There is no database.

How do I run a first agent?

from ragleap_tools import CALCULATOR_TOOL
from ragleap_agents import Agent, Policy, TRUSTED

def my_llm(prompt: str) -> str:
    ...  # call any model, return its text

agent = Agent(
    llm=my_llm,
    tools=[CALCULATOR_TOOL],
    policy=Policy(max_steps=4, tools={"calculator": TRUSTED}),
)
result = agent.run("What is 6 * 7?")
print(result.status, result.answer)   # done, a short summary of what was found
for step in result.steps:             # the transcript: tool, arguments, status, observation
    print(step["tool"], step["arguments"], step["status"])

The tools are ragleap-tools Tool objects. The policy sets a step cap (max_steps=4 here) and marks the calculator as TRUSTED, which the README reserves for tools that neither return external content nor act outside. The result carries a status, an answer and a transcript of every step.

How do I use a real model?

from ragleap_agents import Agent, Policy, TRUSTED, openai_compatible

tools = [CALCULATOR_TOOL]
llm = openai_compatible(
    "https://api.groq.com/openai/v1", api_key, "openai/gpt-oss-20b",
    mode="native", tools=tools,   # or mode="json": the model replies with the JSON action as text
)
agent = Agent(llm, tools, Policy(tools={"calculator": TRUSTED}))
  • https is required (allow_insecure_http=True is for local testing), redirects are refused, responses are size-capped, and 408, 429, 5xx and network errors are retried with backoff (at most 5 retries).
  • You pass the key in. It is never read from the environment and never printed.
  • The base URL is yours to set. There is no address check, so do not build it from untrusted input.

How do I pause for approval and resume?

from ragleap_agents import ToolPolicy

policy = Policy(tools={"write_file": ToolPolicy(taints=False, outbound=True, requires_approval=True)})
agent = Agent(my_llm, tools, policy, store=my_store)

result = agent.run("save the report")
if result.status == "awaiting_approval":
    call = result.pending                 # {"call_id", "tool", "arguments", "forced"}
    # ... show it to a human, then, in this process or another one:
    result = agent.resume(result.run_id, {call["call_id"]: True})   # or False to reject

A tool declared with requires_approval=True pauses the run. A paused run is a plain JSON dict in a StateStore. The in-memory store and a SQLite store (one local file, standard library only, not encrypted) are included; write your own for Redis or a database. If several workers can resume the same run, the store needs an atomic save_if_status, and both shipped stores have it. resume() raises ResumeError if the run is unknown, is not awaiting approval, or the decision does not match the pending call, so an approval cannot be replayed.

Which actions are forced to ask, even if I forget?

Declare each tool with a ToolPolicy: taints (its result is external content) and outbound (it acts on the outside world). Once a tainting tool has run, every later outbound tool needs approval, whatever else is configured. The policy can only tighten. A tool with no declared policy counts as both tainting and outbound, so the loop fails closed.

What limits does the loop have?

  • max_steps defaults to 4, with a hard cap of 8, plus a duplicate-action stop and a deadline checked between calls (a running tool is not interrupted).
  • Every proposal is checked: the tool must exist and the arguments must fit its JSON Schema (required keys, unknown keys, type and enum only). Anything else stops the run and no tool runs.
  • Tool results are untrusted data: capped at 1,500 characters each and 4,000 in the prompt, and fenced in observation tags.
  • run() does not raise for model or tool failures, and a tool's exception text is never shown to the model.

What was observed with a real model?

The README reports one set of runs: Groq, model openai/gpt-oss-20b, 20 labelled tasks per configuration. It is one model on one provider, not a benchmark. With the 0.3.0 wording, 19 of 20 tasks were done in JSON mode and 19 of 20 in native mode, and the README advises native mode for models that have one. Across runs on three models, no model ever proposed the injected send, so the taint rule has not been triggered by a real model. It is tested with scripted models.

What is not covered?

  • It does not stop prompt injection. It limits what an injected instruction can do, and only as far as your ToolPolicy declarations are accurate.
  • Tool descriptions are shown to the model too (capped at 300 characters), so tools from an untrusted source, for example a remote MCP server, can inject through them.
  • Approval prompts are only as good as the human reading them.
  • The SQLite store is not encrypted. For several tenants in one process, see how to isolate tenants.
  • No independent security review has happened.

Sources: the ragleap-agents 0.5.1 release notes, the README at that tag, and PyPI. Library page: ragleap-agents.

Quick answers

How do I add human approval to an AI agent in Python?

Declare the outbound tool with ToolPolicy(requires_approval=True) and give the agent a store. The run pauses with status awaiting_approval; show result.pending to a person, then call agent.resume(run_id, {call_id: True}) or False.

Does ragleap-agents stop prompt injection?

No. It limits what an injected instruction can do, only as far as your ToolPolicy declarations are accurate. Tool results are treated as untrusted, and after a tainting tool runs every outbound tool needs approval.

What happens if a tool has no declared policy?

It counts as both tainting and outbound, so the loop fails closed. Mark a tool TRUSTED only if it neither returns external content nor acts outside.

Can an approval be replayed?

No. resume() raises ResumeError if the run is unknown, not awaiting approval, or the decision does not match the pending call.

Back to the blog