Docs›Bring Your Own Agent

Bring Your Own Agent

Name: Oya
Author: Oya

Two ways to work with Oya from where you already are: drive Oya from your AI tool over MCP, or migrate your existing agent code to run on Oya.

Two paths

Bring your tool — connect Claude Code, claude.ai, Codex, or OpenCode to Oya's MCP server and manage OAgents from your editor or chat.
Bring your agent — take an existing LangChain, Mastra, or Claude Code agent and deploy it to run on Oya.

Note

To connect an external MCP server to an OAgent (the other direction), see MCP Connections. For the deep CLI reference, see Claude Code.

Part 1 — Connect your tool (MCP)

Oya runs its own MCP server at https://oya.ai/api/mcp. Point a supported tool at it and you get a full toolset (~150 tools) that mirrors the Oya API — agents, skills, routines, triggers, knowledge base, templates, projects, organizations, accounts, evals, and gateway management — discovered automatically via tools/list.

Endpoints

Production: https://oya.ai/api/mcp
Dev: https://dev.oya.ai/api/mcp
Local: http://localhost:8000/api/mcp

API key — Claude Code, Codex, OpenCode, CLI

The editor plugins and the oya CLI send an Oya API key as a bearer token. Create one at oya.ai → Oya, then export it:

bash

export OYA_API_KEY="a2a_..."

OAuth — the claude.ai connector (no API key)

claude.ai's custom connector has no field for an API key, so Oya's MCP server is a full OAuth 2.1 server. Add the connector and sign in through the browser with your existing Oya account.

claude.ai: Settings → Connectors → Add custom connector, name it "Oya", paste https://oya.ai/api/mcp, then Connect and finish the browser sign-in.
Claude Code: /plugin marketplace add OyaAIProd/oya-plugins then /plugin install oya
Codex CLI: codex plugin marketplace add OyaAIProd/oya-plugins then codex plugin install oya
OpenCode: add "@oyadotai/opencode-plugin" to opencode.json "plugin"

What you can do

Agents — create/update/delete, soul, skills, deploy, run, memories, debug (runs/threads/traces), export/fork, transfer
Skills, routines, triggers, knowledge base, templates
Gateways — connect (Slack/Gmail/…) and manage; connect token-based platforms (sentry/posthog/kubernetes/browser/attio)
Projects, organizations (members/teams/invitations/grants), accounts (agency), evals, mcp_connections, agent_transfers, api_keys

Tip

Connecting a gateway: gateways.connect returns an install_url to authorize in the browser, or attaches instantly with no browser if you pass a connection_id from gateways.list_connections. Tool results surface URLs (authorize links, chat_url) as clickable links.

Part 2 — Migrate your agent

An Oya script-mode agent is one self-contained Python 3.11 script: input arrives as the USER_MESSAGE env var, stdout is the result, import lines pip-install on deploy, and secrets are env vars. Declare I/O with # INPUT_SCHEMA: / # OUTPUT_SCHEMA: comments. For a keyless LLM call in the sandbox, use oya_runtime.llm(messages) instead of a provider SDK.

The deploy flow (the same steps the migrate commands automate):

text

agents.create (mode "script")
agents.update_script      # your ported code
agents.update_secrets     # the env vars it reads
agents.deploy_script      # pip-installs imports, uploads
agents.deploy
agents.run_script         # smoke-test against the original

LangChain / LangGraph (Python)

A near-direct port: wrap your chain/graph to read USER_MESSAGE and print the result. Map cron jobs to routines and LangChain tools to catalog skills. In Claude Code, run /oya:migrate-langchain.

Mastra (TypeScript)

A reimplementation (the sandbox is Python-only): new Agent → the script's LLM call, createTool → a Python function or an Oya skill, workflows → control flow or a routine, Zod schema → the # INPUT_SCHEMA: comment. In Claude Code, run /oya:migrate-mastra.

Claude Code subagent / Agent SDK

A Claude Code subagent (a .claude/agents/*.md prompt + tool allowlist, no code) maps to a skills-mode agent: set the soul from the system prompt and map its tools to catalog skills (WebSearch → web-search, memory → memory, …). A Claude Agent SDK program (code) migrates like LangChain. In Claude Code, run /oya:migrate-claude-code.

Portable specs (OyaAgentSpec)

Any agent can be exported as a portable OyaAgentSpec v1 (soul + skills + routines, credentials stripped) with agents.export, and re-created elsewhere with agents.fork — handy for sharing or moving an agent between accounts.

Note

Destructive tools (e.g. agents.delete) are irreversible after the retention window — confirm before running. API keys are shown once and stored hashed.