orchagent-public/orchagent-guide

# 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-limits