Tool calling with human approval

Some tools you don’t want the model running unsupervised — sending email, executing code, charging cards. This pattern wires an Approver so the agent loop pauses before specified tools run, surfaces the pending call to a human, and only proceeds when they say yes.

What you’ll build

An agent with two tools — one safe (get_balance), one sensitive (transfer_funds). The safe tool runs without intervention; the sensitive one prompts for approval at a CLI before dispatching.

How it works

with_approver(...) plus the HumanInTheLoop middleware tap into the agent loop’s tool-dispatch step.
Your Approver decides per call. Approve, reject (with a reason the model sees), or edit (rewrite the args before running).
Rejection becomes a tool message. The agent sees “the tool was not approved” and can apologize, ask for clarification, or try a different approach.

The approver

use async_trait::async_trait;
use cognis::tools::{Approver, Decision};
use cognis::Result;
use serde_json::Value;

struct CliApprover {
    sensitive: Vec<&'static str>,
}

#[async_trait]
impl Approver for CliApprover {
    async fn approve(&self, tool_name: &str, args: &Value) -> Result<Decision> {
        if !self.sensitive.contains(&tool_name) {
            return Ok(Decision::Approve);
        }

        println!("\n[approval needed]");
        println!("  tool: {tool_name}");
        println!("  args: {}", serde_json::to_string_pretty(args)?);
        print!("  approve? (y / n / e=edit): ");
        std::io::Write::flush(&mut std::io::stdout())?;

        let mut line = String::new();
        std::io::stdin().read_line(&mut line)?;
        match line.trim() {
            "y" | "yes" => Ok(Decision::Approve),
            "e" | "edit" => {
                print!("  new JSON args: ");
                std::io::Write::flush(&mut std::io::stdout())?;
                let mut edit = String::new();
                std::io::stdin().read_line(&mut edit)?;
                let new_args: Value = serde_json::from_str(edit.trim())?;
                Ok(Decision::Edit { args: new_args })
            }
            _ => Ok(Decision::reject("rejected by operator")),
        }
    }
}

The agent

use std::sync::Arc;
use cognis::prelude::*;
use cognis::AgentBuilder;
use cognis::Client;

#[tokio::main]
async fn main() -> Result<()> {
    let approver = Arc::new(CliApprover {
        sensitive: vec!["transfer_funds"],
    });

    let mut agent = AgentBuilder::new()
        .with_llm(Client::from_env()?)
        .with_tool(Arc::new(GetBalanceTool))     // (your impls)
        .with_tool(Arc::new(TransferFundsTool))
        .with_approver(approver)                 // wraps every registered tool
        .with_system_prompt(
            "You are a banking assistant. Use tools to inspect accounts and \
             move money. Confirm intent in plain English before any transfer.",
        )
        .with_max_iterations(6)
        .build()?;

    let resp = agent.run(Message::human(
        "Move $50 from checking to savings, then tell me the new balances."
    )).await?;
    println!("\n{}", resp.content);
    Ok(())
}

How it works

The approver runs before dispatch. with_approver(...) wraps every registered tool in an ApprovalGatedTool. When the agent’s dispatcher tries to run the tool, the wrapper consults the approver first.
A Reject decision short-circuits the tool, returning the rejection reason as the tool’s output — the agent sees “rejected by operator” and can apologize, retry, or take a different path.
Edit lets the human fix the model’s args without rejecting. Useful when the model picked the right tool but the wrong amount or recipient.
Arc<dyn Approver> is the shape passed in — the builder takes ownership and uses the same instance for every gated tool, so the approver can hold state (a counter, a queue handle, an audit log) without divergence.

Production approver

A CLI approver is a starting point. In production you’d swap in:

Surface	How
Slack	Post the tool + args to a channel; wait for an emoji or button click.
Web UI	Persist the pending call to your DB; poll for the human’s decision.
Mobile push	Push notification with approve / reject quick actions.
Auto-approve under threshold	Approve transfers under $X, prompt above.

The trait is async, so you can wait on a long-lived signal. Just don’t block the agent’s hot path — if approval might take minutes, push to a queue and resume from a checkpoint.

Pair with checkpoints

For long-running approvals (the human is asleep), persist the agent’s state and resume later. Use a Checkpointer and rebuild the agent from state on the resume side. See Graph workflows → Checkpointing for the time-travel surface.

Human-in-the-loop

Approver, Decision, graph interrupts.

Tools

Define the tools being gated.

Checkpointing

Pause across processes.

Get started

Core ideas

Building agents

Building RAG

Graph workflows

Observability

Patterns

Production

Tool calling with human approval

What you’ll build

How it works

The approver

The agent

How it works

Production approver

Pair with checkpoints

See also

Human-in-the-loop

Tools

Checkpointing

​What you’ll build

​How it works

​The approver

​The agent

​How it works

​Production approver

​Pair with checkpoints

​See also

Human-in-the-loop

Tools

Checkpointing

What you’ll build

How it works

The approver

The agent

How it works

Production approver

Pair with checkpoints

See also