> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autonomous AI Agents, Tool Sandboxing & Execution Workflows

> Deploy goal-directed multi-step agents with tool authorization, sandboxed container execution, durable state checkpointing, and human-in-the-loop approval gates.

MITHUNAI autonomous agents execute multi-step technical workflows by combining goal decomposition with sandboxed tool invocation, durable state checkpointing, and mandatory human approval gates for destructive operations. Unlike simple single-turn prompt chains, agents dynamically re-evaluate their progress against intermediate tool outputs until their objective is achieved.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
stateDiagram-v2
    [*] --> Plan: Receive User Goal
    Plan --> Reason: Decompose into Steps
    Reason --> ToolCheck: Select Tool & Parameters

    state ToolCheck <<choice>>
    ToolCheck --> HumanApproval: Tool requires Privileged Permission
    ToolCheck --> ExecuteTool: Tool is Read-Only / Safe

    HumanApproval --> ExecuteTool: Approved by Operator
    HumanApproval --> Abort: Rejected by Operator

    ExecuteTool --> SandboxedEnv: Dispatch in Isolated Container
    SandboxedEnv --> Observe: Return Output & Exit Code
    Observe --> CheckComplete: Evaluate Objective

    state CheckComplete <<choice>>
    CheckComplete --> Reason: More steps required
    CheckComplete --> Synthesize: Goal reached

    Synthesize --> [*]: Stream Final Result with Citations
    Abort --> [*]: Graceful Cancellation
```

## Agent Core Principles

<Columns cols={2}>
  <Card title="Deterministic State Graphs" icon="workflow">
    Workflows are modeled as directed cyclic graphs where state transitions are explicit,
    serializable, and verifiable.
  </Card>

  <Card title="Sandboxed Execution" icon="shield-check">
    Tool execution runs in ephemeral containers with isolated virtual filesystems, CPU quotas, and
    strict egress firewalls.
  </Card>

  <Card title="Human-in-the-Loop Gates" icon="user-check">
    Privileged actions (such as sending external webhooks, creating database records, or modifying
    production files) pause execution until an operator confirms.
  </Card>

  <Card title="Durable Checkpointing" icon="database">
    Agent state is persisted to PostgreSQL after every step, allowing execution to resume without
    data loss after infrastructure restarts.
  </Card>
</Columns>

***

## Tool Authorization & Permission Matrix

Every tool registered in MITHUNAI must declare its access tier:

| Tier                          | Policy                             | Examples                                                             | Approval Requirement                          |
| :---------------------------- | :--------------------------------- | :------------------------------------------------------------------- | :-------------------------------------------- |
| **Tier 1 (Read-Only)**        | Unrestricted within tenant bounds. | `search_knowledge`, `get_document_by_id`, `read_code_ast`.           | Automatic execution.                          |
| **Tier 2 (Idempotent Write)** | Monitored with rate quotas.        | `format_code`, `generate_markdown_report`, `run_unit_test`.          | Automatic execution with audit logging.       |
| **Tier 3 (State Mutating)**   | Privileged execution.              | `create_jira_issue`, `update_notion_page`, `commit_git_patch`.       | Operator notification or configurable policy. |
| **Tier 4 (Destructive)**      | Critical security boundary.        | `delete_collection`, `deploy_production_service`, `send_bulk_email`. | **Mandatory Human-in-the-Loop confirmation.** |

***

## Execution Reentrancy & Crash Recovery

When an agent executes long-running operations across distributed services, network blips or pod rescheduling must not corrupt state. MITHUNAI achieves durable execution through event-sourced step logging:

```json Step Checkpoint Payload theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "agent_id": "agt_8829ef1",
  "run_id": "run_01j8x23e",
  "step_index": 4,
  "state": "waiting_for_approval",
  "plan": [
    { "step": 1, "action": "search_error_logs", "status": "completed" },
    { "step": 2, "action": "identify_failing_commit", "status": "completed" },
    { "step": 3, "action": "draft_hotfix_pr", "status": "completed" },
    { "step": 4, "action": "submit_github_pr", "status": "pending_approval" }
  ],
  "context_snapshot": {
    "target_repo": "acme/billing-service",
    "branch": "fix/err-402-timeout",
    "diff_size_bytes": 1420
  }
}
```

If the execution worker crashes at step 4, a standby worker picks up the run from the database checkpoint and resumes exactly where it left off, avoiding redundant LLM token expenditures and duplicate external actions.