Source code and prompts are visible
You can inspect, fork, and run locally
How to use orchagent - publish, run, and compose AI agents. Use when integrating with orchagent CLI, API, or SDK. Covers calling agents, installing sub-agents, publishing agents and skills, orchestration patterns, skills composition, services, and workspaces.
by orchagent
How to use orchagent - publish, run, and compose AI agents. Use when integrating with orchagent CLI, API, or SDK. Covers calling agents, installing sub-agents, publishing agents and skills, orchestration patterns, skills composition, services, and workspaces.
The full instructions provided by this skill
# orchagent Guide
orchagent is a platform for publishing, running, and composing AI agents — securely.
> The CLI can be invoked as `orchagent` or `orch` (shorthand). This guide uses `orch` throughout.
## When to Use This Skill
- Integrating with orchagent CLI or API
- Publishing an agent or skill
- Calling an existing orchagent agent
- Installing agents as sub-agents for AI coding tools
- Building orchestrator agents that call other agents
- Composing skills with agents
- Deploying always-on services
- Setting up workspaces
> Full documentation: [docs.orchagent.io](https://docs.orchagent.io)
---
## Running Agents (Caller)
> **Before calling an agent:** Run `orch info {org}/{agent}` or check the profile page at `orchagent.io/agents/{org}/{agent}` to see required inputs and schemas.
### Quick Comparison
**orch run** — runs agents on orchagent servers (cloud, default). Requires `orch login`, uses stored keys or `--key` flag. Best for CI/CD and production.
**orch run --local** — runs on your machine, no auth needed, uses your local env vars for LLM keys. Best for local dev and private code/repos.
**orch install** — exports agent as config files for AI tools (Claude Code, Cursor, etc.), no auth needed.
### Cloud Execution (`orch run`, default)
Run agents on orchagent servers:
```bash
# Authenticate first
orch login
# Run with file input
orch run acme/invoice-scanner invoice.pdf
# Run with JSON input
orch run acme/text-extractor --data '{"text": "hello world"}'
# Pipe input
cat document.pdf | orch run acme/pdf-parser
# Specify version
orch run acme/invoice-scanner@v2 invoice.pdf
# Override endpoint
orch run acme/invoice-scanner invoice.pdf --endpoint extract
# Override LLM model (provider auto-detected from model name)
orch run org/agent --data '{"text": "..."}' --key sk-... --model gpt-4o
# Explicit provider override
orch run org/agent --data '{"text": "..."}' --provider anthropic --model claude-sonnet-4-5-20250929
# JSON output for scripting
orch run acme/scanner input.pdf --json
# Save output to file
orch run acme/scanner input.pdf --output result.json
# Compose skills at call time
orch run org/agent --data '...' --skills org/skill1,org/skill2
```
**Supported providers:** `openai`, `anthropic`, `gemini`
**When to use:** CI/CD, public repos, no local setup needed.
### Local Execution (`orch run --local`)
Download and run any agent locally (if the author has enabled local download):
```bash
# Run on a local directory
orch run org/agent --local --data '{"path": "."}'
# Shorthand: scan current directory (for tool agents with a path input field)
orch run org/agent --local --here
# Run on a remote repo
orch run orchagent/leak-finder --local --data '{"repo_url": "https://github.com/user/repo"}'
# Just download without running
orch run org/agent --local --download-only
# Override LLM model (provider auto-detected from model name)
orch run org/agent --local --model claude-sonnet-4-5-20250929 --data '{"text": "..."}'
```
**Supported providers for local:** `openai`, `anthropic`, `gemini`, `ollama`
**When to use:** Local dev, private code, private repos, using your own LLM keys.
**Important:** Tool agents requiring `path` or `directory` input can ONLY access your local files via `orch run --local`. The server cannot see your filesystem.
### Installing as Sub-Agent (`orch install`)
Export agents as sub-agents for AI coding tools:
```bash
# Install for Claude Code (default format)
orch install org/agent
# Install for Cursor
orch install org/agent --format cursor
# Install globally (home directory)
orch install org/agent --global
# Install for multiple tools
orch install org/agent --format claude-code,cursor
# Preview without installing
orch install org/agent --dry-run
# Update installed agents to latest versions
orch update
# Check for updates without installing
orch update --check
```
**Supported formats:** `claude-code` (default), `cursor`, `amp`, `opencode`, `antigravity`
**Install skills locally:**
```bash
orch skill install org/skill-name
orch skill install org/skill-name --global
orch skill install org/skill-name --format cursor
orch skill uninstall org/skill-name
```
### API Integration
Direct HTTP calls to agents:
```http
POST https://api.orchagent.io/{org}/{agent}/{version}/{endpoint}
Authorization: Bearer {api_key}
Content-Type: application/json
```
**Required headers:**
- `Authorization: Bearer {api_key}` - Your orchagent API key
**Optional headers:**
- `X-Orchagent-Max-Hops: 2` - Limit call chain depth
- `X-Orchagent-Tenant: tenant_slug` - Multi-tenant usage attribution
- `X-Orchagent-Skills: skill1,skill2` - Add skills to inject
- `X-Orchagent-Skills-Only: skill1` - Use only these skills (override defaults)
- `X-Orchagent-No-Skills: true` - Disable all skills
- `X-Orchagent-Deadline-Ms: 1234567890` - Request deadline (epoch ms)
**LLM credentials (BYOK):** Pass in the request body (not headers):
```json
{
"text": "input data here",
"llm_credentials": {
"api_key": "sk-...",
"provider": "openai",
"model": "gpt-4o"
}
}
```
**Example — file upload:**
```http
POST https://api.orchagent.io/acme/invoice-scanner/v1/analyze
Authorization: Bearer sk_live_xxx
Content-Type: multipart/form-data
file=@invoice.pdf
```
**Example — JSON with BYOK:**
```http
POST https://api.orchagent.io/org/agent/v1/analyze
Authorization: Bearer {your_api_key}
Content-Type: application/json
{
"text": "analyze this",
"llm_credentials": {
"api_key": "sk-...",
"provider": "openai"
}
}
```
### CI/CD Integration
Use environment variables - no interactive login needed:
```bash
# Set API key (no orch login required)
export ORCHAGENT_API_KEY=sk_live_xxx
# Now run agents directly
orch run acme/scanner input.pdf
# JSON output for parsing
orch run acme/scanner input.pdf --json
# Save output to file
orch run acme/scanner input.pdf --output result.json
```
**Exit codes for scripting:**
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Authentication error |
| 3 | Permission denied |
| 4 | Not found (agent doesn't exist) |
| 5 | Invalid input |
| 6 | Rate limited |
| 7 | Timeout |
| 8 | Server error |
| 9 | Network error |
### Bring Your Own Key (BYOK)
orchagent uses a BYOK model - you supply your own LLM API keys.
**Key resolution order:**
1. `--key` flag (CLI) or `llm_credentials` in request body (API)
2. Environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`)
3. Workspace secrets vault (via `orch secrets set` or dashboard)
**For cloud execution (`orch run`):**
```bash
# Pass key directly
orch run org/agent --data '...' --key sk-... --provider openai
# Or store keys in workspace vault for reuse
orch secrets set ANTHROPIC_API_KEY sk-ant-...
```
**For local execution (`orch run --local`):** Set environment variables:
```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
orch run org/agent --local --data '{"text": "..."}'
# Or override with flags:
orch run org/agent --local --provider anthropic --model claude-sonnet-4-5-20250929 --data '...'
```
---
## Publishing (Author)
### Agent Types
**prompt** — Prompt template + schema. No code. Key files: orchagent.json, prompt.md, schema.json
**tool** — Full Python/JS agent. Runs in sandbox. Key files: orchagent.json, main.py, requirements.txt
**skill** — Knowledge/instructions for AI. Key file: SKILL.md only
**agent** — LLM-powered agent with tool use. Key files: orchagent.json, prompt.md, optional code
### Publishing a Prompt Agent
1. Initialize:
```bash
orch init --type prompt
```
2. Edit `orchagent.json`:
```json
{
"name": "my-agent",
"type": "prompt",
"description": "What this agent does",
"supported_providers": ["openai", "anthropic", "gemini"],
"default_endpoint": "run"
}
```
3. Write `prompt.md` with your prompt template (use `{{variable}}` placeholders).
4. Write `schema.json` with input/output schemas.
5. Publish:
```bash
orch publish
```
**Important:** The prompt comes from `prompt.md`, NOT from orchagent.json. Schemas come from `schema.json`, NOT from orchagent.json fields.
Local download is enabled by default. To make server-only: `orch publish --no-local-download`
Publish all agents in a monorepo: `orch publish --all` (auto-detects ordering from dependencies). Use `--dry-run` to preview.
Versions auto-increment on each publish (v1, v2, v3...).
### Publishing a Skill
Skills are simpler - just a `SKILL.md` file:
1. Create directory with `SKILL.md`:
```yaml
---
name: my-skill
description: When to use this skill and what it does.
license: MIT
metadata:
author: yourname
version: "1.0"
---
# Skill Title
Instructions for the AI assistant...
```
2. Publish:
```bash
cd my-skill-dir
orch publish
```
### Publishing a Tool Agent
For agents requiring custom code:
1. Initialize:
```bash
orch init --type tool
```
2. Edit `orchagent.json`:
```json
{
"name": "my-agent",
"type": "tool",
"description": "What this agent does",
"supported_providers": ["anthropic"],
"required_secrets": ["ANTHROPIC_API_KEY"],
"entrypoint": "main.py"
}
```
3. Write your agent code. It receives JSON via stdin and outputs JSON via stdout.
4. Publish:
```bash
# Publish with bundle (auto-detects Python/JS, max 50MB)
orch publish
# With custom Docker environment
orch publish --docker
```
> For the deep builder guide (sandbox internals, boilerplate code, env vars, debugging): `orch skill install orchagent-public/agent-builder`
---
## Orchestration (Agent-to-Agent)
Build agents that call other agents.
### Declare Dependencies
In `orchagent.json`:
```json
{
"name": "security-review",
"type": "agent",
"supported_providers": ["any"],
"manifest": {
"manifest_version": 1,
"dependencies": [
{ "id": "joe/leak-finder", "version": "v1" },
{ "id": "joe/vuln-scanner", "version": "v1" }
],
"orchestration_mode": "strict",
"max_hops": 2,
"timeout_ms": 120000
}
}
```
**Orchestration mode:** Orchestrators with dependencies default to `"strict"` — bash is disabled and the agent must use its declared dependencies. Set `"orchestration_mode": "flexible"` to keep bash available. In multi-agent chains, strict mode inherits downward (strict parent forces strict children).
**Optional manifest fields:** `orchestration_mode`, `region`, `visibility`, `min_required_hops`, `recommended_min_caller_budget`
**Validation rules:**
- If `dependencies` is declared, `max_hops` must be >= 1
- Versions must be pinned (no "latest")
- Dependency graph must be acyclic
### Use the Python SDK
Install: `pip install orchagent-sdk`
```python
# pip install orchagent-sdk (package name)
from orchagent import AgentClient # module name
# Standard: reads ORCHAGENT_SERVICE_KEY + context from env vars (auto-injected by gateway)
client = AgentClient()
# Call dependencies
secrets = await client.call("joe/leak-finder@v1", {"url": repo_url})
vulns = await client.call("joe/vuln-scanner@v1", {"url": repo_url})
```
This is the standard pattern for tool-type and agent-type orchestrators (stdin/stdout). The gateway auto-injects `ORCHAGENT_SERVICE_KEY` and orchestration context as env vars.
**Advanced — custom FastAPI server:** If you're running a custom HTTP server (not stdin/stdout), use `AgentClient.from_request(request)` to propagate call chain, deadline, and billing context from HTTP headers:
```python
from fastapi import Request
@app.post("/review")
async def review(request: Request, input: ReviewInput):
client = AgentClient.from_request(request)
result = await client.call("joe/leak-finder@v1", {"url": input.repo_url})
return {"findings": result}
```
### Parallel Calls
```python
import asyncio
secrets, vulns, licenses = await asyncio.gather(
client.call("joe/leak-finder@v1", {"url": repo}),
client.call("joe/vuln-scanner@v1", {"url": repo}),
client.call("joe/license-checker@v1", {"url": repo}),
)
```
### Error Handling
```python
from orchagent import (
DependencyCallError,
TimeoutExceededError,
CallChainCycleError,
LocalExecutionError,
)
try:
result = await client.call("org/agent@v1", data)
except DependencyCallError as e:
print(f"Agent error: {e.status_code} - {e.response_body}")
except TimeoutExceededError:
print("Deadline exceeded")
except CallChainCycleError:
print("Circular dependency detected")
except LocalExecutionError as e:
print(f"Local execution failed: exit {e.exit_code}")
```
### Local Orchestrator Development
```bash
# Auto-download all dependencies
orch run joe/security-review --with-deps --input '{"path": "."}'
```
---
## Skills Composition
Attach reusable knowledge to agent calls:
```bash
# Add skills at call time
orch run org/agent --data '...' --skills org/skill1,org/skill2
# Use ONLY these skills (replace defaults)
orch run org/agent --data '...' --skills-only org/custom-skill
# Disable all skills
orch run org/agent --data '...' --no-skills
```
**Default skills in manifest:**
```json
{
"default_skills": ["vercel/react-best-practices", "org/coding-standards"],
"skills_locked": false
}
```
**Skill locking:** Set `"skills_locked": true` (or `--skills-locked` during publish) to prevent callers from overriding skills via headers. This setting is immutable after publishing.
**How skills work:**
- **Prompt agents:** Skills prepend to the agent's prompt
- **Tool agents:** Skills mount as files at `$ORCHAGENT_SKILLS_DIR`
---
## Always-On Services
Deploy long-running agents (Discord bots, webhooks, monitors):
```json
// orchagent.json
{
"name": "my-bot",
"type": "agent",
"run_mode": "always_on",
"runtime": { "command": "python main.py" },
"supported_providers": ["anthropic"],
"required_secrets": ["DISCORD_BOT_TOKEN", "ANTHROPIC_API_KEY"]
}
```
```bash
# Publish
orch publish
# Add secrets to workspace vault
orch secrets set DISCORD_BOT_TOKEN "your-token"
orch secrets set ANTHROPIC_API_KEY "sk-ant-..."
# Deploy — required_secrets auto-resolved from vault
orch service deploy org/my-bot
# Pass non-sensitive config via --env
orch service deploy org/my-bot --env DISCORD_CHANNEL_IDS=123456
# Use --secret only for extras not in required_secrets
orch service deploy org/my-bot --secret MONITORING_TOKEN
# Manage services
orch service list
orch service logs <service-id>
orch service restart <service-id>
orch service delete <service-id>
```
**Requirements:** Agent must have `"run_mode": "always_on"` and `"runtime": {"command": "..."}` in orchagent.json. Secrets must exist in the workspace vault before deploying.
---
## Discovery
### Finding Agent Documentation
**Check an agent's profile page:**
```
https://orchagent.io/agents/{org}/{agent}
```
The profile page shows:
- Required vs optional inputs
- Whether the agent needs `repo_url`, `path`, or file uploads
- Whether to use `orch run` (cloud) or `orch run --local`
- Input/output schemas
### View Agent Info
```bash
orch info org/agent
orch info org/agent --json
```
---
## Workspaces
Collaborate with teams:
```bash
orch workspace create "My Team"
orch workspace list
orch workspace use my-team
orch workspace invite user@example.com --role member
orch workspace members
orch workspace leave
```
---
## Configuration
Config stored at `~/.orchagent/config.json`:
```json
{
"api_key": "sk_live_xxx",
"api_url": "https://api.orchagent.io",
"default_org": "myorg",
"default_formats": ["claude-code", "cursor"],
"default_scope": "project",
"default_provider": "anthropic",
"profiles": {
"staging": { "api_key": "sk_staging_xxx", "api_url": "https://staging.api.orchagent.io" }
}
}
```
**Environment variables (for CI/CD):**
```bash
export ORCHAGENT_API_KEY=sk_live_xxx
export ORCHAGENT_API_URL=https://api.orchagent.io
export ORCHAGENT_DEFAULT_ORG=myorg
```
**Manage config:**
```bash
orch config set default-format cursor
orch config get default-format
orch config list
```
### Useful Commands
```bash
orch doctor # Diagnose setup issues
orch test # Run agent tests locally (pytest/vitest)
orch test --watch # Watch mode
orch dev # Local dev server with hot-reload (port 4900)
orch formats # List available export formats
orch secrets list # List workspace secrets
orch secrets set KEY val # Add/update a secret
```
### Debugging & Observability
```bash
orch trace <run-id> # View execution trace (LLM calls, tokens, costs)
orch replay <run-id> # Re-execute a previous run from snapshot
orch dag <run-id> # Visualize orchestration call graph
orch dag <run-id> --live # Live mode — polls while run is active
orch diff org/agent@v1 v2 # Compare two agent versions
orch metrics # Workspace performance metrics (success rates, latency)
orch metrics --days 7 # Filter to last 7 days
orch estimate org/agent # Show estimated cost based on historical runs
orch security test org/agent # Run vulnerability scan (prompt agents)
```
---
## Rate Limits
See the plans table at [orchagent.io/plans](https://orchagent.io/plans) for current limits (executions, concurrency, timeouts) per tier.
Orchestrator sub-calls don't count against the caller's limit — only the top-level call does.
Rate limit headers in responses:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1704067200
```
---
## Quick Reference
| Task | Command |
|------|---------|
| Authenticate | `orch login` |
| Run (cloud) | `orch run org/agent --data '{...}'` |
| Run locally | `orch run org/agent --local --data '{...}'` |
| Install sub-agent | `orch install org/agent` |
| Install skill | `orch skill install org/skill` |
| Update installed | `orch update` |
| Agent info | `orch info org/agent` |
| Publish | `orch publish` |
| Initialize | `orch init --type prompt` |
| Test locally | `orch test` |
| Dev server | `orch dev` |
| Diagnose | `orch doctor` |
| Deploy service | `orch service deploy org/agent` |
| Set secret | `orch secrets set KEY value` |
| Billing portal | `orch billing` |
| Execution trace | `orch trace <run-id>` |
| Replay a run | `orch replay <run-id>` |
| Call graph | `orch dag <run-id>` |
| Compare versions | `orch diff org/agent@v1 v2` |
| Metrics | `orch metrics` |
| Cost estimate | `orch estimate org/agent` |
| Security scan | `orch security test org/agent` |
---
## Full Documentation
- Quickstart: https://docs.orchagent.io/quickstart
- CLI Commands: https://docs.orchagent.io/using-agents/cli-commands
- API Reference: https://docs.orchagent.io/using-agents/api-reference
- Agent Types: https://docs.orchagent.io/building-agents/agent-types
- Manifest Format: https://docs.orchagent.io/building-agents/manifest-format
- Publishing: https://docs.orchagent.io/building-agents/publishing
- Orchestration: https://docs.orchagent.io/building-agents/orchestration
- BYOK: https://docs.orchagent.io/concepts/byok
- Rate Limits: https://docs.orchagent.io/concepts/rate-limitsSkills are knowledge files for AI tools. Install locally to use with Claude Code, Cursor, etc.
Install to current project
orch skill install orchagent-public/orchagent-guideInstall globally (all projects)
orch skill install orchagent-public/orchagent-guide --globalOnce installed, your AI tool will automatically use this skill's knowledge.
Input and output data structures
Integrate this agent via CLI or API
POST /orchagent-public/orchagent-guide/v17/runFree: 1,000 runs/day# Install (one-time)
npm install -g orchagent
# Call the agent
orch run orchagent-public/orchagent-guide --data '{"variable":"..."}'Get your API key from the dashboard