# Interactive & Human-in-the-Loop

> Implementing interactive flows using run_interactive_loop and ask_user policy handlers for manual tool call approval.

- Repository: google-antigravity/antigravity-sdk-python
- GitHub: https://github.com/google-antigravity/antigravity-sdk-python
- Human wiki: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867
- Complete Markdown: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867/llms-full.txt

## Source Files

- `google/antigravity/utils/interactive.py`
- `examples/getting_started/human_in_the_loop.py`
- `examples/deep_dives/interactive_cli.py`
- `google/antigravity/utils/interactive_test.py`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [google/antigravity/utils/interactive.py](google/antigravity/utils/interactive.py)
- [google/antigravity/agent.py](google/antigravity/agent.py)
- [examples/getting_started/human_in_the_loop.py](examples/getting_started/human_in_the_loop.py)
- [examples/deep_dives/interactive_cli.py](examples/deep_dives/interactive_cli.py)
- [google/antigravity/utils/interactive_test.py](google/antigravity/utils/interactive_test.py)
</details>

# Interactive & Human-in-the-Loop

The Google Antigravity SDK provides robust support for interactive workflows, allowing developers to keep a "human-in-the-loop" (HITL) for critical operations. This is achieved through a combination of policy handlers for tool approval and specialized hooks for direct agent-to-user communication. These utilities are primarily housed in the `google.antigravity.utils.interactive` module and are designed to facilitate local development, debugging, and safe execution of autonomous agents.

Interactivity in Antigravity typically takes two forms: **Tool Call Approval**, where a user must explicitly permit the agent to execute a specific tool (like running a shell command), and **Active Questioning**, where the agent pauses its execution to request clarification or missing information from the user via the `ask_question` tool.

## Core Interactive Utilities

The SDK provides several pre-built components to enable interactive CLI sessions without requiring custom logic for stdin/stdout handling.

### Interactive Loop REPL
The `run_interactive_loop` function is the primary entry point for creating a terminal-based REPL. It manages the conversation lifecycle, handles user input via an asynchronous wrapper for `input()`, and automatically wires up interactive hooks.

Sources: [google/antigravity/utils/interactive.py:244-292]()

### Tool Confirmation Handlers
For tool-level safety, the SDK offers two primary ways to prompt the user:
1.  **`ask_user_handler`**: A convenient handler designed for the policy system. When a tool call matches a policy configured with `policy.ask_user`, this handler prints the tool arguments and waits for a `y/n` response.
2.  **`ToolConfirmationHook`**: A lower-level `PreToolCallDecideHook` that can be registered directly with an agent to intercept and confirm tool calls.

Sources: [google/antigravity/utils/interactive.py:80-129]()

### Active Questioning with `AskQuestionHook`
The `AskQuestionHook` enables the `ask_question` capability. When an agent invokes this tool, the hook intercepts the request, presents the questions (and any multiple-choice options) to the user, and returns the user's answers back to the agent as tool output.

Sources: [google/antigravity/utils/interactive.py:132-190]()

## Implementing Human-in-the-Loop

Implementing HITL involves configuring the agent's policies and hooks during initialization. The following table summarizes the typical configuration options:

| Component | Usage | Description |
| :--- | :--- | :--- |
| `policy.ask_user` | `policies=[policy.ask_user("*", handler=ask_user_handler)]` | Prompts for confirmation on every tool call. |
| `AskQuestionHook` | `hooks=[AskQuestionHook()]` | Enables the agent to ask the user questions. |
| `run_interactive_loop` | `await run_interactive_loop(agent)` | Starts a full CLI REPL with automatic policy "upgrades". |

### Policy-Based Tool Approval
By default, sensitive tools like `run_command` may be denied in certain configurations. `run_interactive_loop` automatically "upgrades" these denials to `ASK_USER` prompts, ensuring a smooth developer experience without compromising the underlying safety model.

```python
# From examples/deep_dives/interactive_cli.py:130-142
config = LocalAgentConfig(
    tools=[read_file_upside_down],
    mcp_servers=[mcp_server],
    # Wire all tool calls to the interactive CLI handler
    policies=[policy.ask_user("*", handler=interactive.ask_user_handler)],
    hooks=[interactive.AskQuestionHook()],
)
```

### Interactive Flow Sequence
The following diagram illustrates the sequence of an interactive tool call approval using the policy system:

```mermaid
sequenceDiagram
    participant User
    participant Agent
    participant PolicyHook as Policy (ask_user_handler)
    participant Tool as Tool Implementation

    Agent->>PolicyHook: Request Tool Call (e.g. run_command)
    Note over PolicyHook: Display arguments to User
    PolicyHook->>User: "Allow execution? (y/n)"
    User-->>PolicyHook: "y"
    PolicyHook-->>Agent: Allow: True
    Agent->>Tool: Execute Tool
    Tool-->>Agent: Tool Result
    Agent->>User: Final Response
```

## Practical Examples

### Basic HITL Questioning
In a simple script, you can register the `AskQuestionHook` to allow the agent to clarify ambiguous prompts.

```python
# From examples/getting_started/human_in_the_loop.py:41-43
async with Agent(config) as my_agent:
    # Register the hook to handle questions from the agent.
    my_agent.register_hook(interactive.AskQuestionHook())
```

### Full Interactive CLI
For a complete debugging environment, use `run_interactive_loop` which handles the REPL logic and automatically configures standard interactive hooks and policy upgrades.

```python
# From google/antigravity/utils/interactive.py:269-270
agent.register_hook(AskQuestionHook())
_upgrade_to_interactive_confirmation(agent)
```

Interactive utilities in Antigravity ensure that autonomous agents remain transparent and controllable, providing a seamless bridge between automated execution and human oversight.

Sources: [google/antigravity/agent.py:123-137]()