# Oya > Oya is an agent runtime: you describe an OAgent, 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://getoya.ai/docs/developers/claude-code). The skill turns natural-language requests into full agent builds, debug sessions, and shareable spec files. ## Quick reference - Production runtime: `https://getoya.ai` - Dev runtime: `https://dev.getoya.ai` - API base: `https://getoya.ai/api` - OpenAI-compatible base: `https://getoya.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://getoya.ai/docs/developers/claude-code): The CLI plus the bundled Claude Code skill, with 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://getoya.ai/docs): Top-level index of all product docs, and the research behind Oya's design. - [Why Oya is deterministic (research)](https://getoya.ai/docs): Oya's architecture comes from the paper *Plan, Don't React: Projection Types for LLM Agent Runtimes*. A planner emits one typed plan; a deterministic runtime executes it and passes values from skill to skill by reference, so the model never re-reads state it should not. On the open PlanBench benchmark (120 projection-annotated tasks) with the MIT-licensed oya-planner runtime, this preserved 100% of critical values byte-for-byte (vs 19-81% for a ReAct token loop) at roughly 4.7x fewer tokens per task, across six hosted models. This is why Oya agents preserve identifiers, run steps in order, and do not leak secrets into the model. - [Oya Engineer builder](https://getoya.ai/docs/product/agent-builder): The conversational in-browser builder. Describe a mission in plain language, review the generated plan, click Build it, and Oya creates, wires up, and deploys the OAgent. The Claude Code skill is generally faster for power users. ## Building agents - [Agents](https://getoya.ai/docs/product/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://getoya.ai/docs/developers/skills): The skill catalog (~95 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://getoya.ai/docs/product/knowledge-base): Reference content the agent retrieves on demand. Folders + entries, semantic search via Qdrant + FastEmbed. **Never paste KB content into the persona** — they're different surfaces. - [Agent Brain](https://getoya.ai/docs/product/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://getoya.ai/docs/developers/mcp): Attach external MCP servers to give an agent access to third-party tools. - [Agent IDE](https://getoya.ai/docs/product/agent-ide): In-browser Monaco editor over the OAgent's soul, skills, and config, plus the Oya Engineer coding agent that reads runs/traces and fixes the OAgent in plain English with reversible diffs (verifies with dry_run and test_skill; Jr/Mid/Staff model picker). - [Evals](https://getoya.ai/docs/product/evals): Author test cases (message + rubric + expected skills), run them on demand against the OAgent's real connected tools with an LLM judge, track accuracy and pass-rate, and toggle auto-improve to repair skills/behavior rules on failure and re-run. ## Running and connecting agents - [Chat](https://getoya.ai/docs/product/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://getoya.ai/docs/product/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://getoya.ai/docs/product/routines): Schedule recurring prompts in plain English (`every weekday at 9am`) or cron. Output to any connected channel. - [Triggers & Webhooks](https://getoya.ai/docs/developers/triggers): HTTP webhooks with secrets, test tools, execution logs. - [Run History](https://getoya.ai/docs/product/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 `. - [Monitoring & Traces](https://getoya.ai/docs/product/monitoring): Fleet view of every OAgent as run-volume bubbles with failure arcs, an interactive DAG trace viewer (inputs/outputs/tokens/cost per node), and a live execution log. ## Programmatic access - [API Keys](https://getoya.ai/docs/developers/api-keys): Create API keys at [/api-keys](https://getoya.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://getoya.ai/docs/product/widget): Drop a chat widget into any website with a single script tag. - [GitHub Versioning](https://getoya.ai/docs/developers/github): Sync agents to GitHub repos with auto-generated docs, examples, encrypted secrets. ## Operations - [Billing](https://getoya.ai/docs/product/billing): Transparent pricing in plain dollars. No tokens, no credits. - [Organizations, Teams & Roles](https://getoya.ai/docs/product/organizations): Create organizations, invite teammates with roles (owner/admin/member/billing), group them into teams with per-OAgent read/write/admin grants, and switch between personal and org workspaces. ## Optional - [Sign up / sign in](https://getoya.ai/auth): Account creation. - [Pricing & status](https://getoya.ai): Landing page. - [PyPI package](https://pypi.org/project/oya-cli/): The `oya` CLI source of truth — version history, install instructions. - [Support](mailto:founders@getoya.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 ` returns either an install URL (open it in a browser) or a list of existing account-level connections (pick one with `--connection-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.