# AgentForms Examples — Human-in-the-Loop Patterns

Demonstrations of integrating [AgentForms](https://agentforms.io) with popular AI agent frameworks. Each example shows a complete flow: **create form → send link to human → receive response → continue workflow**.

---

## Quick Start

```bash
export AGENTFORMS_API_KEY="your-api-key"
pip install agentforms requests
```

---

## Example 1: CrewAI Human-in-the-Loop

**File:** `crewai_human_in_loop.py`

A CrewAI agent generates content (e.g. a blog post), then pauses to request human approval before publishing.

**Pattern:**
1. Agent generates a draft.
2. Agent creates an AgentForms approval form with the SDK.
3. Shareable link is sent to the human reviewer.
4. Agent polls the API for a submission.
5. Based on the response (approve / revise / stop), the agent continues, revises, or halts.

**Key classes:**
- `ApprovalGate` — creates the form, shares the link, polls until the human responds.
- `build_crew_ai_agent()` — full CrewAI workflow with approval gating.

**Run:**
```bash
pip install crewai agentforms
python crewai_human_in_loop.py
```

**When to use:** Content generation pipelines, code review gates, deployment approvals — any workflow where an agent's output needs human sign-off before proceeding.

---

## Example 2: LangChain Form Generator Agent

**File:** `langchain_form_agent.py`

A LangChain agent that dynamically generates AgentForms from natural-language prompts.

**Pattern:**
1. Human describes a form in plain English.
2. LangChain agent calls either:
   - `generate_agentform(prompt)` — AgentForms' built-in AI generates fields.
   - `create_agentform(name, fields)` — Agent builds the fields programmatically.
3. The agent returns a shareable form URL.
4. Optionally, the agent polls for and summarises collected submissions.

**Key tools:**
- `generate_agentform` — AI-powered form generation (Starter+ tier).
- `create_agentform` — Programmatic form creation with explicit field definitions.
- `poll_submissions` — Wait for and summarise form responses.

**Run:**
```bash
# Direct SDK demo (no LangChain needed):
pip install agentforms
python langchain_form_agent.py

# Full LangChain agent:
pip install langchain langchain-openai agentforms
python langchain_form_agent.py langchain
```

**When to use:** Dynamic data collection, user-facing agents that need to gather structured input, survey generation, onboarding flows.

---

## Example 3: Webhook Receiver (FastAPI / Flask)

**File:** `webhook_receiver.py`

A webhook server that receives AgentForms submissions and unblocks a waiting agent — eliminating the need for polling.

**Architecture:**
```
┌──────────┐   share URL    ┌───────────┐   webhook POST   ┌──────────────┐
│  Agent   │ ─────────────► │  Human    │ ───────────────► │  Webhook     │
│  (AI)    │ ◄───────────── │  (Browser)│                  │  Receiver    │
└──────────┘   resume       └───────────┘   (async signal) └──────────────┘
```

**Pattern:**
1. Agent creates a form with a webhook URL pointing to this server.
2. Agent shares the form link with a human and waits on a shared channel.
3. Human fills out the form; AgentForms POSTs to the webhook URL.
4. Webhook handler parses the payload and signals the waiting agent.
5. Agent resumes with the human's decision.

**Key components:**
- `PendingRequests` — in-memory store matching webhook payloads to pending agent sessions.
- `WebhookApprovalGate` — agent-facing class that creates forms and waits for webhook delivery.
- `build_fastapi_app()` — FastAPI webhook endpoint with health and status checks.
- `build_flask_app()` — Flask alternative.

**Run:**
```bash
# Start FastAPI server:
pip install fastapi uvicorn agentforms
python webhook_receiver.py server

# Start Flask server:
pip install flask agentforms
python webhook_receiver.py flask

# Run the full demo (creates form, starts server, simulates webhook):
python webhook_receiver.py demo
```

**Webhook payload format:**
```json
{
  "event": "submission",
  "site_id": 42,
  "site_name": "Approval Request",
  "submission_id": 156,
  "submitted_at": "2026-06-12T14:30:00Z",
  "fields": {
    "approved": "Yes",
    "revision_notes": "Looks good, proceed."
  },
  "field_metadata": {}
}
```

**When to use:** Production deployments where polling is undesirable, real-time workflows, systems with strict latency requirements, or when you need audit logging of webhook deliveries.

---

## Comparison

| Aspect | `crewai_human_in_loop` | `langchain_form_agent` | `webhook_receiver` |
|---|---|---|---|
| **Pattern** | Agent polls after creating form | Agent generates forms on demand | Webhook pushes response to agent |
| **Transport** | Polling (simple) | Polling (simple) | Webhook (real-time) |
| **Best for** | Approval gates, review loops | Dynamic form creation | Production, low-latency flows |
| **Framework** | CrewAI | LangChain | FastAPI / Flask |
| **Complexity** | Low | Medium | Medium-High |

---

## SDK Reference

All examples use the [AgentForms Python SDK](../sdk-python/):

```python
from agentforms import AgentForms

af = AgentForms(api_key="afk_live_...")

# Create a form
form = af.forms.create(
    name="My Form",
    fields=[
        {"name": "field_name", "label": "Label", "type": "text", "required": True},
        {"name": "choice", "label": "Choose", "type": "select",
         "options": ["A", "B", "C"], "required": True},
    ],
)
print(form.share_url)  # Share this with the human

# Or generate with AI
form = af.forms.generate(prompt="A food preference form for catering")

# List submissions
subs = af.submissions.list(form_token=form.token)
```

Full API docs: https://agentforms.io/api/v2