# Omni Octo

Version: 0.1.0

> Omni Octo is a platform that lets business users create, configure, and deploy AI agents through conversation. The agent persona is Octo, a friendly octopus mascot.

Omni Octo provides an MCP server that exposes tools for creating and managing AI agents. Agents are defined using a YAML blueprint schema, stored in Supabase, and served via a Hono API. The platform supports webchat, voice, SMS, WhatsApp, Messenger, Instagram, and LINE channels.

## Quick Start

Here is a complete example of creating a customer support agent and getting a test link:

```
// Step 1: Create the agent from a YAML blueprint
create_agent(yaml: """
agent:
  name: "Acme Support"
  description: "Customer support agent for Acme Corp"
  language: en-US

persona:
  display_name: "Acme Support"
  tone: friendly
  greeting: "Hi! I'm Acme Support. How can I help you today?"

llm:
  provider: anthropic
  model: claude-sonnet-4-6
  temperature: 0.3
  max_tokens: 1024

system_prompt: |
  You are Acme Support, the customer support agent for Acme Corp.
  Help users with product questions, order status, and returns.
  Escalate billing disputes to a human agent.
""")
// → { success: true, agentId: "uuid", testUrl: "http://localhost:3002/test/uuid" }

// Step 2: Crawl the company knowledge base
crawl_website(agent_id: "<agentId>", url: "https://help.acme.com", depth: 2)
// → { success: true, status: "pending" }

// Step 3: Get the test link
generate_test_link(agent_id: "<agentId>")
// → { success: true, testUrl: "http://localhost:3002/test/<agentId>" }
```

## MCP Server

The MCP server exposes all agent management tools over HTTP using the Streamable HTTP transport.

**Endpoint:** `http://localhost:3001/mcp`
**Method:** POST
**Auth:** Bearer token — pass an API key in the `Authorization` header:
```
Authorization: Bearer <your-api-key>
```

API keys are generated via `POST /api/keys` (requires a valid session). Each key is scoped to an organization.

## MCP Tools

### create_agent
Create a new AI agent from a YAML blueprint. Call this after the user approves the blueprint.

Parameters:
- `yaml` (string, required): The complete agent blueprint YAML string.

Returns: `{ success, agentId, agentName, status, testUrl, warnings }`

---

### update_agent
Update an existing agent's configuration.

Parameters:
- `agent_id` (string uuid, required): The agent to update.
- `updates` (object, required): Fields to update. All fields are optional:
  - `name` (string)
  - `description` (string)
  - `status` (enum: enabled | disabled — disabled stops the agent everywhere: no replies, no calls, no campaigns, no deployments)
  - `language` (string)
  - `displayName` (string)
  - `tone` (enum: friendly | professional | casual | formal)
  - `greeting` (string)
  - `llmProvider` (string)
  - `llmModel` (string)
  - `temperature` (number)
  - `maxTokens` (integer)
  - `systemPrompt` (string)
  - `businessRules` (object)
  - `labels` (string[])
  - `toolsConfig` (object[])

Returns: `{ success, agentId, agentName }`

---

### get_agent
Get an agent by ID or name. Returns full agent details including configuration.

Parameters:
- `agent_id` (string uuid, optional): The agent UUID. Preferred over name.
- `name` (string, optional): Agent name to search for (case-insensitive). Used if no ID provided.

At least one of `agent_id` or `name` must be provided.

Returns: `{ success, agent, disclosure }` or `{ success, agents, total }` for name searches (each agent in `agents` also carries `disclosure`). `disclosure` is `{ enabled, applies, note, mode, spoken_text, using_default_text, recording_id }` — a plain-language summary of whether the AI/recording disclosure applies to this agent right now.

---

### list_agents
List all AI agents in the user's organization.

Parameters:
- `status` (enum, optional): Filter by state — enabled | disabled.

Returns: `{ success, agents: [{ id, name, status, createdAt }], total }`

---

### crawl_website
Crawl a website URL and add it as a knowledge base source for an agent.

Parameters:
- `agent_id` (string uuid, required): The agent ID to add the KB source to.
- `url` (string url, required): Website URL to crawl.
- `depth` (integer 1–5, default 2): Crawl depth.

Returns: `{ success, knowledgeBaseId, sourceId, url, status, message }`

---

### generate_test_link
Generate a test link for a created agent.

Parameters:
- `agent_id` (string uuid, required): The agent ID.

Returns: `{ success, testUrl, embedUrl, agentName, note }` — `embedUrl` is `null` when the agent has no webchat deployment.

---

### deploy_agent
Deploy an agent to a channel (webchat, voice, SMS, etc.).

Parameters:
- `agent_id` (string uuid, required): The agent ID to deploy.
- `channel` (enum, required): webchat | twilio_voice | sms | whatsapp | messenger | instagram | line
- `config` (object, optional): Channel-specific configuration.

Returns: `{ success, deploymentId, channel, message }`, plus `channelName`, `inbound`, and an optional `note` (and `replacedAgentId` when inbound ownership moved) when deploying via `channel_id`.

---

### get_conversations
Retrieve recent conversations for an agent.

Parameters:
- `agent_id` (string uuid, required): The agent ID.
- `limit` (integer 1–100, default 20): Number of conversations to return.

Returns: `{ success, conversations: [{ id, status, channel, labels, createdAt }], total }`

---

### get_analytics
Get basic analytics for an agent (conversation count, label distribution).

Parameters:
- `agent_id` (string uuid, required): The agent ID.

Returns: `{ success, agentId, agentName, totalConversations, labelCounts }`

---

### delete_agent
Permanently delete an agent and all associated data (knowledge base, deployments). This cannot be undone.

Parameters:
- `agent_id` (string uuid, required): The agent ID to delete.

Returns: `{ success, agentId, agentName }`

---

### Bulk operations

Delete or modify MANY resources of the same kind in one confirmed call, instead
of looping a per-item tool. Each takes **either** a `filter` OR an explicit
`ids` list, and (for destructive ones) parks a single confirmation stating the
count + a sample. Prefer these whenever a request affects many rows.

- `delete_conversations` — filter by `status` / `channel` / `contact_id` / `source` / `older_than` / `all`. Removes the conversations and their messages.
- `delete_channels` — filter by `provider` / `status` / `all`. Also removes the channels' deployments.
- `delete_contacts` — filter by `tag` / `list_id` / `all`. Soft delete (recoverable).
- `delete_campaigns` — filter by `status` / `all` (skips running unless `include_running: true`).
- `undeploy_agents` — filter by `agent_id` / `channel_id` / `all`. Stops those agents receiving from those channels.
- `cancel_campaigns` — filter by `status` / `all`. Cancels in-flight campaigns (safe; no confirmation).

A `filter` of `{ all: true }` requires a matching `confirm_count` to proceed,
and a confirmation is drift-aborted if the matching set grows >10% before you
confirm. Returns: `{ success, requested, affected, skipped?, sample }`.

---

## Blueprint YAML Schema

Agents are defined using a YAML blueprint. All blueprints are validated against this schema before creation.

```yaml
agent:
  name: string (1–100 chars, required)
  description: string (max 500 chars, optional)
  language: BCP 47 code e.g. en-US, zh-TW (required)

persona:
  display_name: string (1–50 chars, required)
  tone: friendly | professional | casual | formal (required)
  greeting: string (1–500 chars, required)

llm:
  provider: anthropic | openai | google (required)
  model: string (required)
  temperature: 0.0–2.0 (required)
  max_tokens: 1–8192 (required)

system_prompt: |
  string (10–10000 chars, required)

knowledge_base:  # optional
  sources:  # 0–20 items
    - type: website_crawl | file_upload | markdown_file | api | manual_text
      url: string  # for website_crawl
      depth: 1–5   # for website_crawl, default 2
      path: string # for markdown_file

channels:  # optional, 0–10 items
  - type: webchat | twilio_voice | sms | whatsapp | messenger | instagram | line
    config: {}  # channel-specific key/value config

business_rules:  # optional
  business_hours:
    timezone: IANA timezone string
    schedule:
      monday: { start: "HH:MM", end: "HH:MM" } | null
      tuesday: { start: "HH:MM", end: "HH:MM" } | null
      wednesday: { start: "HH:MM", end: "HH:MM" } | null
      thursday: { start: "HH:MM", end: "HH:MM" } | null
      friday: { start: "HH:MM", end: "HH:MM" } | null
      saturday: { start: "HH:MM", end: "HH:MM" } | null
      sunday: { start: "HH:MM", end: "HH:MM" } | null
    after_hours_message: string (max 500 chars, optional)
  escalation:
    enabled: boolean
    trigger: after_2_failed_attempts | user_request | keyword_match | sentiment
    action: collect_contact | transfer_to_human | email_notification
    notification_email: email string (optional)
  blocked_topics: string[]  # topics the agent should not discuss

labels: string[]  # 0–50 conversation labels

tools:  # optional
  - type: search_knowledge_base | apply_label | http_webhook | http_request
    enabled: boolean (default true)
    config: {}  # tool-specific config
```

## REST API

In addition to the MCP server, the platform exposes a REST API:

- `GET  /health` — Health check (no auth)
- `GET  /llms.txt` — This file (no auth)
- `GET  /api/agents` — List agents
- `GET  /api/agents/:id` — Get agent by ID
- `POST /api/agents` — Create agent
- `PATCH /api/agents/:id` — Update agent
- `POST /api/agents/:id/chat` — Chat with a deployed agent (streaming)
- `POST /api/chat` — Chat with Octo, the agent builder (streaming)
- `POST /api/keys` — Generate API key
- `GET  /api/keys` — List API keys
- `DELETE /api/keys/:id` — Revoke API key
- `POST /mcp` — MCP endpoint (Streamable HTTP)

Agent-subscribable events (OpenAI-compatible `/v1` host, Bearer API key):

- `POST/GET/PATCH/DELETE /v1/webhooks` — Manage outbound webhook subscriptions (signed, retried deliveries)
- `GET  /v1/events` — Server-Sent Events feed of workspace events with a `?after=<seq>` / `Last-Event-ID` resume cursor
- Event types: `conversation.created`, `turn.completed`, `confirmation.requested`, `confirmation.resolved`, `spend.recorded`, `run.completed`. See https://docs.omniocto.com/openai-api/events/

All `/api/*` routes require `Authorization: Bearer <token>` except `/health` and `/llms.txt`.
In development (NODE_ENV != production), unauthenticated requests use the seeded dev user.