Folder Structure

The orcha/ directory is the source of truth. Placement determines behavior, so an agent remains understandable by opening its folder.

orcha/
  index.ts
  supportAgent/
    index.json
    instructions.md
    actions/
      lookupOrder/
        index.json
        index.js
    skills/
      delayedOrderHandling/
        index.json
        instructions.md
    tests/
      delayedOrder/
        index.json
    evaluations/
      supportQuality/
        index.json

orcha/index.tsCopy Anchor Link

Initializes providers and explicitly registers agents:

import { orcha } from "orchajs";

orcha.init({
  providers: {
    openai: process.env.OPENAI_API_KEY ?? "",
  },
  agents: {
    supportAgent: "./supportAgent",
  },
});

Only registered agents are compiled. The registration key becomes the runtime property: orcha.supportAgent.

Agent filesCopy Anchor Link

agent/index.jsonCopy Anchor Link

Chooses the provider, model, output type, and model limits. name, provider, and model are required.

{
  "name": "Support Agent",
  "description": "Resolves order questions using confirmed order data.",
  "provider": "openai",
  "model": "gpt-5-mini",
  "maxTokens": 4000,
  "outputType": "text"
}

agent/instructions.mdCopy Anchor Link

Contains stable behavior: role, boundaries, decision rules, and guidance for tools. Keep changing user input out of this file and pass it to run() instead.

You help customers understand their orders.

Always look up an order before making claims about its status.
Never invent order data.

Prompt variables use {{ variableName }} and are supplied once when the session is created.

actions/Copy Anchor Link

Actions let the model do work. Every direct child folder has metadata in index.json. Local actions also have executable index.js.

actions/
  lookupOrder/
    index.json
    index.js

• Omit execution for a local action.
• Use "execution": "client" when the caller must do the work.
• Direct child folders are discovered automatically.

skills/Copy Anchor Link

Skills are procedures loaded only when relevant:

skills/
  delayedOrderHandling/
    index.json
    instructions.md

index.json is the small discovery card. instructions.md is the full procedure. Orcha initially exposes only the card, keeping the base prompt small.

tests/Copy Anchor Link

Each direct child is one model-backed contract test:

tests/
  delayedOrder/
    index.json

The test defines an input, action mocks, and deterministic expectations. The folder name is its CLI selector: orcha test supportAgent/delayedOrder.

evaluations/Copy Anchor Link

Each direct child configures an asynchronous model judge:

evaluations/
  supportQuality/
    index.json

Evaluations score qualities such as grounding or clarity. Tests check deterministic contracts; evaluations check probabilistic quality.

Generated .orcha/Copy Anchor Link

.orcha/ is generated output, not source:

.orcha/
  dist/
    bundle.js
  sessions/
    supportAgent/
      ses_...jsonl
  .build/
  .cli/

dist/ is the production agent bundle. .build/ and .cli/ are temporary compiler artifacts. Do not edit or commit any of them. Access sessions through agent.get(), history(), events(), and list() rather than reading storage files directly.

Discovery rulesCopy Anchor Link

• Agents and subagents must be registered in orcha/index.ts.
• Actions, skills, tests, and evaluations are discovered from direct child folders.
• Set "enabled": false in an item's index.json to keep work in progress inactive.
• Enabled entries must contain their required files.
• Model-facing names must be unique within an agent.
• Invalid files and schemas fail during orcha dev or orcha build, before a user run.