Facio's HITL Tool Suite: How ask_approval, ask_form, and ask_selection Keep Humans in Control

Most AI agent platforms offer exactly one human interaction primitive: a binary approve/reject button. The agent proposes something, the human clicks yes or no, and the workflow continues. Useful — but not nearly enough for production systems where human input ranges from "confirm this deployment" to "enter a multi-field configuration" to "review and edit a 2,000-word draft before it ships."

Facio ships with four HITL tools, each designed for a specific class of human-agent interaction. Together they form a complete interaction surface — and they all land in the same Placet.io inbox the human already uses for messaging. Here's the full toolkit and when to reach for each.

The Four Tools at a Glance

Each tool blocks the agent session until the human responds or the timeout expires. If the timeout fires, the agent is notified — it doesn't guess what the human would have chosen.

ask_approval: Beyond Yes/No

The approval tool looks simple on the surface — present a decision, wait for a response — but the API is designed for real-world decision complexity.

ask_approval(
    title="Delete production database backup from 2025-03?",
    description="This backup is 13 months old and exceeds retention policy. The agent will permanently delete it from S3.",
    options=[
        {"id": "delete", "label": "Delete Backup", "style": "danger"},
        {"id": "archive", "label": "Move to Glacier", "style": "secondary"},
        {"id": "skip", "label": "Skip for Now", "style": "ghost"}
    ],
    allow_comment=True,
    timeout=3600
)

Three things make this production-grade:

Custom options with visual styling. The style field maps to button styling: primary for the recommended action, danger for destructive options, secondary for alternatives, ghost for neutral/dismiss actions. The human sees a visual hierarchy, not a wall of identical buttons.

Comment capture. Setting allow_comment=True gives the human a free-text field alongside the buttons. "Approved, but notify the team first" — one interaction, not two.

Timeout handling. The agent specifies how long it's willing to wait. For a database deletion, maybe an hour (wait for the DBA to see it). For a routine content publish, maybe 10 minutes. If time runs out, the agent receives an expiration notice — and can choose to retry, escalate, or skip.

ask_form: Structured Input Without Building a UI

The form tool collects structured data across multiple fields in a single interaction. No separate form builder, no webhook wiring, no frontend code.

ask_form(
    title="New MCP Server Configuration",
    fields=[
        {"key": "server_name", "label": "Server Name", "type": "text", "required_field": True},
        {"key": "server_url", "label": "Server URL", "type": "url", "required_field": True},
        {"key": "auth_token", "label": "Auth Token", "type": "password", "required_field": True},
        {"key": "environment", "label": "Environment", "type": "select", 
         "options": ["staging", "production"], "default_value": "staging"},
        {"key": "auto_restart", "label": "Auto-restart on failure", "type": "checkbox"}
    ]
)

The field types cover real needs: text, number, checkbox, select, textarea, email, url, date, time, datetime, range, and critically — password.

Password fields route directly to the credential store. When a field has type: "password", the raw value goes from the human's input straight into Facio's credential store. The agent receives ${credentials.SERVER_AUTH_TOKEN} — a placeholder, never the raw secret. This is how the HITL layer and the credential store work together: structured human input that keeps secrets out of agent context windows.

The agent gets back a clean key-value response: {"server_name": "weather-api", "environment": "production", "auto_restart": true, "auth_token": "${credentials.SERVER_AUTH_TOKEN}"}. Parse it, validate it, act on it — all without the agent ever seeing a password.

ask_selection: Choices That Scale

When the human needs to pick from a list, ask_selection handles single and multi-select with descriptions for each option. This is the tool for direction-setting, not just confirmation.

ask_selection(
    prompt="Which content pillars should the Q3 strategy focus on?",
    options=[
        {"id": "hitl", "label": "Human-in-the-Loop", 
         "description": "Approval patterns, compliance, audit trails"},
        {"id": "browser", "label": "Browser Automation", 
         "description": "Web agents, persistent sessions, form automation"},
        {"id": "skills", "label": "Agent Skills", 
         "description": "Extensibility, custom modules, MCP integration"},
        {"id": "multi-agent", "label": "Multi-Agent Systems", 
         "description": "Spawn, orchestration, parallel execution"}
    ],
    multiple=True
)

The description field makes each option self-documenting. The human doesn't need to know what "Agent Skills" means in Facio's context — the description explains it inline. For multi-select (multiple=True), the response is an array of IDs: ["hitl", "browser", "skills"].

This tool replaces the friction points where agents typically guess: which category does this blog post belong to? Which deployment environment should I use? Which social platform should this content go to? The agent presents structured options, the human picks, and the guesswork disappears.

ask_text_input: Review Before It Ships

The text input tool is designed for content review workflows — the pattern where an agent drafts something and a human edits before publication.

ask_text_input(
    prompt="Review the blog post draft below. Edit as needed, then submit to publish.",
    prefill="# Facio's HITL Tools: A Complete Guide\n\nHuman-in-the-Loop...",
    markdown=True
)

Two features make this work for real editing workflows:

Prefill with markdown preview. Setting markdown=True renders the pre-filled content as formatted markdown — headings, code blocks, tables, links. The human sees what the final output will look like, not raw markdown source. They can edit in the same rendered view and submit.

Draft → Review → Publish pattern. The agent writes a draft, presents it via ask_text_input(prefill=...), the human edits, and the agent receives the final version. This is the core pattern for content pipelines: blog posts, social media posts, documentation, email campaigns, release notes. The agent does the drafting labor; the human provides editorial judgment.

Integration: How These Tools Land in the Human's World

All four tools deliver their prompts to the same place: the Placet.io inbox. No separate dashboard. No agent-specific monitoring console. The human sees an approval card, a form, a selection list, or a text editor — in the same interface they use for messages.

This matters because it eliminates the "check the agent dashboard" friction. If a deployment needs approval, the human sees it alongside their regular messages. If a form needs filling out, it's one tap away. The HITL interaction doesn't require context-switching to a separate tool.

Timeout expiration is handled gracefully. If a review times out, the agent receives the expiration and can decide: retry with a longer timeout, escalate to a different channel, or skip and log. The agent never assumes approval or rejection — it always responds to an explicit signal.

A Complete Workflow: From Draft to Published Post

Here's what a content publishing pipeline looks like end-to-end with the full HITL suite:

1. Agent researches and drafts a blog post
2. ask_text_input — agent presents the draft with prefill and markdown=true
3. Human edits and submits the final version
4. ask_selection — agent asks which category and tags to use
5. ask_approval — agent confirms publish with a danger-styled "Publish Now" button
6. Human approves → agent publishes
7. Audit trail captures every interaction: draft submitted, human edited, category selected, publish approved

Every step is tracked. Every decision is attributable. The agent did the work, the human made the calls, and the record is complete.

Bottom Line

Human-in-the-Loop isn't just a checkbox on a compliance form — it's a design discipline. The quality of the interaction surface determines whether humans engage meaningfully or click "approve" on autopilot.

Facio's four HITL tools cover the full spectrum of human-agent interaction: binary decisions, structured forms, multi-option selections, and free-text review. They integrate with the credential store for secret-safe input, with Placet.io for inbox-native delivery, and with the audit trail for complete traceability.

Because when the architecture gives humans the right tool for each decision — not just a generic "yes/no" button — the quality of the decisions improves. And in production systems, the quality of the decisions is the whole point.

---

See the HITL tools documentation for API references, timeout patterns, and channel routing configuration.