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 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
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 skipBuilding blocks you'd compose
- Tool risk metadata — declare
requiresConfirmation()on your@Toolmethod or POJO, plusgetRiskLevel()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-backedWsToolApprovalFilteror an HTTP-webhook variant.- Tracing — every approval / denial / modification emits a
DecisionTracerevent you can ship to OpenTelemetry.
Related
- Reference: Agent reliability — error handling, guardrails, retries.
- Server module — websocket protocol + approval-channel internals.
Tutorial: Multi-Agent Research Team
A full code walkthrough is still being written. In the meantime this page describes the topology and points at the framework pieces you can wire up today. Open a discussion if you start the implementation and hit something missing.
Help
Support content: fix problems, look up answers, upgrade between versions.