# Oya

> Oya is an agent runtime: you describe an AI employee, Oya generates the agent, deploys it in a sandbox, and exposes it via chat, webhooks, schedules, an OpenAI-compatible API, or a Claude Code skill.

This file follows the [llmstxt.org](https://llmstxt.org) format. It's a hand-curated index of the most useful pages for an LLM to read when answering questions about Oya, building on Oya, or operating an Oya agent on a user's behalf.

The fastest place to *do* things on Oya is the **`oya` CLI** ([PyPI](https://pypi.org/project/oya-cli/)) and its bundled **Claude Code skill** — both are documented at [/docs/claude-code](https://oya.ai/docs/claude-code). The skill turns natural-language requests into full agent builds, debug sessions, and shareable spec files.

## Quick reference

- Production runtime: `https://oya.ai`
- Dev runtime: `https://dev.oya.ai`
- API base: `https://oya.ai/api`
- OpenAI-compatible base: `https://oya.ai/v1`
- Status / logs / runs are visible in the dashboard once an agent is deployed
- CLI: `pipx install oya-cli && oya login && oya install-claude-skill`

## Start here

- [Claude Code](https://oya.ai/docs/claude-code): The CLI + the bundled Claude Code skill — three flows (build, debug, share). What an LLM-driven session looks like, the full command reference, the OyaAgentSpec v1 portable format, custom skill authoring, KB-vs-persona rule.
- [Documentation Overview](https://oya.ai/docs): Top-level index of all product docs.
- [Pre-built AI Employees (Templates)](https://oya.ai/docs/templates): One-click deployable templates — AI SDR, Executive Assistant, ICP Outreach, LinkedIn SDR, LinkedIn Influencer, Discord support bot, etc. The fastest way to get a working agent is to fork a template.
- [Agent Builder](https://oya.ai/docs/agent-builder): Step-by-step UI for building agents (the wizard). The Claude Code skill is generally faster.

## Building agents

- [Agents](https://oya.ai/docs/agents): How agents are structured — soul (persona, behavior_rules, welcome_message), mode (`skills` vs `script`), config, deploy_status. Manage agents from the dashboard or the CLI.
- [Skills](https://oya.ai/docs/skills): The skill catalog (~80 skills grouped by use case), platform skills (auto-wired from gateways), core skills (always on), addon skills (user-pickable), and authoring custom skills (`SKILL.md` + `script.py`, uploaded via `oya import`).
- [Knowledge Base](https://oya.ai/docs/knowledge-base): Reference content the agent retrieves on demand. Folders + entries, semantic search via ChromaDB + FastEmbed. **Never paste KB content into the persona** — they're different surfaces.
- [Agent Brain](https://oya.ai/docs/agent-brain): A persistent markdown scratchpad the agent maintains autonomously across conversations. Use for cumulative state (running notes, lead status, project context).
- [MCP Connections](https://oya.ai/docs/mcp): Attach external MCP servers to give an agent access to third-party tools.

## Running and connecting agents

- [Chat](https://oya.ai/docs/chat): SSE streaming chat with thread sidebar, run-tree traces, markdown rendering, Mermaid diagrams. The default place users interact with their agents.
- [Channels & Apps (Gateways)](https://oya.ai/docs/gateways): Connect Slack, Discord, Telegram, WhatsApp, Instagram DM, LinkedIn Messaging, Facebook Messenger, X DM, Gmail, Google Calendar, Google Drive, Google Sheets, Google Ads/Analytics/Business, ClickUp, Jira, LinkedIn, X, Apollo, Hunter, Brevo, Instantly, Sentry, PostHog, Kubernetes. Account-level (connect once, reuse across agents).
- [Routines](https://oya.ai/docs/routines): Schedule recurring prompts in plain English (`every weekday at 9am`) or cron. Output to any connected channel.
- [Triggers & Webhooks](https://oya.ai/docs/triggers): HTTP webhooks with secrets, test tools, execution logs.
- [Run History](https://oya.ai/docs/runs): Browse past runs with input/output details, filters, status indicators. Each run links to a `job_id` you can drill into via `oya agent run <id> <job_id>`.

## Programmatic access

- [API Keys](https://oya.ai/docs/api-keys): Create API keys at [/api-keys](https://oya.ai/api-keys). Use as `Authorization: Bearer a2a_…` or `X-API-Key: a2a_…`. Account-scoped (work across all your agents) or agent-scoped.
- [Embeddable Widget](https://oya.ai/docs/widget): Drop a chat widget into any website with a single script tag.
- [GitHub Versioning](https://oya.ai/docs/github): Sync agents to GitHub repos with auto-generated docs, examples, encrypted secrets.

## Operations

- [Billing](https://oya.ai/docs/billing): Transparent pricing in plain dollars. No tokens, no credits.

## Optional

- [Sign up / sign in](https://oya.ai/auth): Account creation.
- [Pricing & status](https://oya.ai): Landing page.
- [PyPI package](https://pypi.org/project/oya-cli/): The `oya` CLI source of truth — version history, install instructions.
- [Support](mailto:founders@oya.ai): Direct contact for help with anything not in the docs.

## Conventions for LLMs operating an Oya account

When an LLM is helping a user *do* things on Oya (not just answer questions), the canonical interface is the `oya` CLI driven from Claude Code. The skill at `~/.claude/skills/oya/` ships with full reference docs (failure cookbook, skill catalog, gateway cookbook, agent cookbook, skill authoring) — read those instead of guessing.

Hard rules to follow:

1. **Build complete agents, not toys.** Soul + 8–14 skills + ≥2 routines + KB for any reference content + connected gateways. Templates already meet this bar; from-scratch builds are held to it.
2. **KB and persona are different surfaces.** Persona is loaded every turn — keep it tight (~6-line persona, 6–10 rules). KB is retrieved on demand — that's where playbooks, ICP, FAQs go. Never inline KB content into the persona as a workaround for a failed upload.
3. **Author missing skills, don't squeeze into `rest-api`.** When the agent needs a capability that isn't in the catalog, write a new `SKILL.md` + `script.py`, `oya import` it, attach it. The new skill is reusable across all the user's future agents.
4. **OAuth requires a browser.** `oya agent gateway connect <id> <platform>` returns either an install URL (open it in a browser) or a list of existing account-level connections (pick one with `--connection-id <id>`). Never try to scrape/inject the OAuth callback.
5. **Pre-deploy check.** Before `oya agent deploy`, verify: soul has persona/rules/welcome, ≥8 skills attached, ≥2 routines, required gateways connected, KB entries for any reference content. Don't deploy a partial agent unless the user explicitly asks for one.