# iraa.ai

> DemoAgent by iraa.ai: AI-powered interactive product demo platform. Deploy an AI agent that gives every website visitor a live, personalized product demo — no scheduling, no pre-recorded tours.

DemoAgent lets SaaS companies embed a conversational AI widget on their website that navigates the actual product in a live iframe, answers questions, and captures leads. It uses a multi-agent architecture (Router, Demo, Q&A, Discovery, Docs) powered by Claude to deliver intelligent, context-aware demos.

## Docs

- [What is PDP?](https://iraa.ai/pdp): Product Discovery Protocol (PDP) — iraa.ai's open YAML spec for AI demo agents. Plain-English explainer.
- [PDP Schema Reference](https://iraa.ai/docs/pdp): Full schema for the YAML spec that defines your product's screens, flows, demo journey, and agent behavior
- [Widget Integration](https://iraa.ai/docs/widget): Embed the DemoAgent chat widget on any website with a single script tag or React/Next.js component
- [REST API Reference](https://iraa.ai/docs/api): Session management, PDP upload, authentication, analytics, and discovery endpoints
- [WebSocket API](https://iraa.ai/docs/websocket): Real-time bidirectional chat protocol for live demo sessions

## Quick Start

1. Sign up at https://iraa.ai/signup and get your API key at https://iraa.ai/dashboard/keys (`pk_live_...` for client / `sk_live_...` for server)
2. Define your product with a PDP YAML file (or use auto-discovery)
3. Add the widget to your site:

```html
<script src="https://cdn.iraa.ai/widget.js" data-api-key="pk_live_YOUR_KEY" async></script>
```

Or initialize programmatically:

```js
DemoAgent.init({
  apiKey: 'pk_live_YOUR_KEY',
  theme: 'auto',        // 'light' | 'dark' | 'auto'
  position: 'bottom-right' // 'bottom-right' | 'bottom-left'
});
```

## API Base URL

`https://api.iraa.ai`

## Authentication

- **Public keys** (`pk_live_*`, `pk_test_*`): Used in client-side widget code. Domain-restricted.
- **Secret keys** (`sk_live_*`, `sk_test_*`): Used in server-side code for admin operations (PDP upload, analytics).
- Pass via `Authorization: Bearer <key>` header.

## Key Concepts

- **PDP (Product Discovery Protocol)**: A YAML file that describes your product's screens, UI elements, demo flows, FAQ knowledge, and agent configuration. This is the single source of truth for how DemoAgent interacts with your product.
- **Sessions**: Each visitor gets a unique demo session with its own conversation history, agent state, and lead capture flow.
- **Flows**: Scripted step-by-step product walkthroughs (navigate, click, type, highlight) that the AI agent can execute.
- **Multi-Agent System**: Router agent classifies visitor intent and delegates to specialized agents (Demo, Q&A, Discovery, Docs).

## Agent-to-Agent Integration

DemoAgent is designed to be invoked by other AI agents. Three integration paths:

### MCP Server (for Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent)

**One-line install for Claude Code:**
```bash
claude mcp add iraaai -- npx -y @iraaai/mcp-server
```

**Claude Desktop / Cursor / Windsurf — add to MCP config:**
```json
{
  "mcpServers": {
    "iraaai": {
      "command": "npx",
      "args": ["-y", "@iraaai/mcp-server"],
      "env": { "IRAAAI_API_KEY": "sk_live_YOUR_KEY" }
    }
  }
}
```

**Onboarding mode:** the MCP server starts even without `IRAAAI_API_KEY`. Three onboarding tools (`get_started`, `how_to_get_api_key`, `about_demoagent`) walk the user through generating a free key. Authenticated tools return a structured "needs auth" payload with the signup URL when the key is missing — so a calling agent can guide the user end-to-end without ever seeing a dead transport.

**Tools:** get_started, how_to_get_api_key, about_demoagent, list_available_demos, start_demo_session, send_demo_message, capture_lead, create_demo_link, run_headless_demo

**Get an API key:** sign up free at https://iraa.ai/signup, then create a secret key at https://iraa.ai/dashboard/keys (no credit card required).

### Partner API (for any HTTP-capable agent)
- `POST /api/v1/partner/demo-link` — Generate pre-seeded demo URLs with visitor context
- `POST /api/v1/partner/headless` — Run a full demo conversation programmatically (no UI)
- `POST /api/v1/partner/embed` — Get iframe embed snippet

### Discovery Endpoints
- `GET /.well-known/agent.json` — A2A Agent Card
- `GET /.well-known/ai-plugin.json` — OpenAI plugin manifest
- `GET /.well-known/openapi.json` — Full OpenAPI 3.1 spec

## npm Packages

- `@iraaai/mcp-server` — MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible agent
- `@iraaai/sdk` — Headless TypeScript SDK for programmatic demo sessions

## Optional

- [Full Documentation](https://iraa.ai/llms-full.txt): Complete API reference, PDP schema spec, and integration examples