# agentforms

Python SDK for AgentForms — programmatic form lifecycle for AI agents.

## Install

```bash
pip install agentforms
```

## Quick Start

```python
from agentforms import AgentForms

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

# Create a form
form = af.forms.create(
    name="Customer Feedback",
    fields=[
        {"name": "rating", "label": "Rating", "type": "select",
         "options": ["1", "2", "3", "4", "5"], "required": True},
        {"name": "feedback", "label": "Feedback", "type": "textarea"},
    ],
)
print(form.share_url)  # https://agentforms.io/{token}

# Or generate with AI (Starter tier+)
form = af.forms.generate(
    prompt="Build a job application form for a restaurant"
)

# Read submissions
subs = af.submissions.list(form.token)
for sub in subs["submissions"]:
    print(sub.dynamic_data)
```

## Human-in-the-Loop Pattern

The core agent pattern: agent needs human input → creates form → sends link → waits for webhook.

```python
from agentforms import AgentForms

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

# 1. Agent creates a decision gate
form = af.forms.create(
    name="Approval Request",
    metadata={"session_id": "conv_123", "agent_turn": 7},
    fields=[
        {"name": "approved", "label": "Do you approve?", "type": "select",
         "options": ["Yes", "No"], "required": True},
        {"name": "notes", "label": "Notes", "type": "textarea"},
    ],
)

# 2. Send the link to the human (via your messaging channel)
send_to_user(f"Please review: {form.share_url}")

# 3. Webhook fires when submitted → your agent continues
# Webhook payload:
#   {event: "submission", site_id: ..., fields: {approved: "Yes", notes: "..."}}
```

## Webhook Payload Schema

When a human submits a form, AgentForms POSTs to your configured webhook:

```json
{
  "event": "submission",
  "site_id": 42,
  "site_name": "Approval Request",
  "submission_id": 156,
  "submitted_at": "2026-06-12T14:30:00Z",
  "fields": {
    "approved": "Yes",
    "notes": "Looks good"
  },
  "field_metadata": {
    "visible_fields": {...},
    "computed_fields": {...},
    "applied_conditions": []
  }
}
```

See [OpenAPI spec](../openapi/openapi.yaml) for full reference.

## API Reference

| Method | Description |
|--------|-------------|
| `af.forms.create(name, fields)` | Create form with explicit fields |
| `af.forms.generate(prompt)` | AI generate form from prompt |
| `af.forms.get(token)` | Get form details |
| `af.forms.update_fields(token, fields)` | Replace all fields |
| `af.forms.delete(token)` | Delete form + submissions |
| `af.forms.list(limit, offset)` | List all forms |
| `af.submissions.list(token)` | List submissions for a form |
| `af.submissions.get(token, sub_id)` | Get single submission |
| `af.keys.create(name, permissions)` | Create API key |
| `af.keys.list()` | List API keys |
| `af.keys.revoke(key_id)` | Revoke API key |

## Error Handling

```python
from agentforms import AgentFormsError

try:
    form = af.forms.create(name="Test", fields=[])
except AgentFormsError as e:
    print(f"API error {e.status_code}: {e}")
```

## Agent Framework Examples

See [examples/](../examples/) for:
- [CrewAI human-in-the-loop](../examples/crewai_human_in_loop.py)
- [LangChain agent with form](../examples/langchain_form_agent.py)