---
title: Tutorial — Agent with Tool Approval
description: End-to-end walkthrough is in progress. This page sketches the approval-gated tool path and points at the framework pieces involved.
---

# Tutorial: Agent with Tool Approval

A full code walkthrough is still being written. In the meantime this page describes the shape and points at the framework pieces you can wire up today. [Open a discussion](https://github.com/TnsAI-Framework/TnsAI/discussions) if you start the implementation and hit something missing.

## Goal

An agent that uses destructive tools (shell, `git` writes, DB mutations) safely by routing them through a human approval channel before they execute.

## How approval flows through the framework

```text
LLM proposes tool call ──▶ ToolCallFilter (per-session)
                              │
                              ├─ tool.requiresConfirmation() == false ─▶ execute immediately
                              │
                              └─ tool.requiresConfirmation() == true  ─▶ pause + emit approval event
                                                                          │
                                                                          ▼
                                                                  Approval channel
                                                                  (WebSocket UI / webhook / chat /custom)
                                                                          │
                                                                          ▼
                                                                  Approve / Deny / Modify
                                                                          │
                                                                          ▼
                                                            Resume tool execution or skip
```

## Building blocks you'd compose

- **Tool risk metadata** — declare `requiresConfirmation()` on your `@Tool` method or POJO, plus `getRiskLevel()` so the approval UI can surface the right context.
- **`tnsai-server`** — runs the WebSocket protocol that streams pending approval events and accepts the operator's response.
- **`ToolCallFilter`** — the per-session interceptor that pauses execution and waits for the approval channel. The default filter blocks indefinitely; production setups wire either a websocket-backed `WsToolApprovalFilter` or an HTTP-webhook variant.
- **Tracing** — every approval / denial / modification emits a `DecisionTracer` event you can ship to OpenTelemetry.

## Related

- [Reference: Agent reliability](../agents/reliability/index.md) — error handling, guardrails, retries.
- [Server module](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-server) — websocket protocol + approval-channel internals.