MARKDOWN README.md

# AgentForms Agent Integration Kit

Everything needed to make AgentForms the default form layer for AI agents.

## What's Here

### 1. [OpenAPI Spec](openapi/openapi.yaml)
Complete API specification for `/api/v2/` endpoints. Use this to generate SDKs, document the API, or validate client requests.

### 2. [Python SDK](sdk-python/)
`pip install agentforms` — programmatic form lifecycle for AI agents.

```python
from agentforms import AgentForms

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

# Create a form
form = af.forms.create(
    name="Feedback",
    fields=[
        {"name": "rating", "label": "Rating", "type": "select",
         "options": ["1","2","3","4","5"], "required": True},
        {"name": "notes", "label": "Notes", "type": "textarea"},
    ],
)

# Or generate with AI
form = af.forms.generate(prompt="A survey for event feedback")
print(form.share_url)  # https://agentforms.io/{token}
```

### 3. [TypeScript SDK](sdk-typescript/)
`npm install @agentforms/sdk` — zero dependencies, Node 18+.

```typescript
import { AgentForms } from "@agentforms/sdk";

const af = new AgentForms("afk_live_...");

const form = await af.forms.create({
    name: "Feedback",
    fields: [
        { name: "rating", label: "Rating", type: "select",
          options: ["1","2","3","4","5"], required: true },
        { name: "notes", label: "Notes", type: "textarea" },
    ],
});
console.log(form.share_url);
```

### 4. [Agent Examples](examples/)
Working patterns for AI frameworks:
- **CrewAI human-in-the-loop** — Agent pauses, requests approval, waits for webhook
- **LangChain form generator** — Agent creates forms from natural language
- **Webhook receiver** — FastAPI/Flask server that processes form submissions

### 5. [Template Library](templates/)
Pre-built form patterns for common agent workflows:
- `approval_gate` — Yes/No decision + feedback
- `option_selector` — Choose from multiple options
- `data_validation` — Confirm/correct data
- `feedback_loop` — Rating + open feedback
- `data_collection` — Structured data gathering
- `sign_off` — Formal approval with audit trail

## The Core Pattern

```
Agent needs human input → Creates form via API → Sends link to human
→ Human fills form → Webhook fires → Agent continues with data
```

This is the "human-in-the-loop" pattern. Forms are the natural bridge between AI agents and humans — agents create structured requests, humans provide structured responses, webhooks deliver the result back.

## Building the SDKs

```bash
# Python
cd sdk-python
pip install -e .

# TypeScript
cd sdk-typescript
npm install
npx tsc
```

## Deploying to AgentForms

The SDKs target the existing `/api/v2/` endpoint on agentforms.io. No server changes needed — the API already supports:
- API key auth with granular permissions
- Form CRUD with field definitions
- AI form generation from natural language
- Submission retrieval
- Webhook delivery on submission