orcha-builder

# ORCHA Resource Schemas ## Agents (`agents/<name>.agent.yaml`) ```yaml name: my-agent description: What the agent does model: llm: default temperature: 0.7 prompt: system: | Your system prompt here. inputVariables: - query tools: # mcp:<server> | knowledge:<store> | function:<name> - mcp:server-name # builtin:<name> | sandbox:<tool> | workspace:<tool> - knowledge:store-name # workspace: read, write, delete, list, list_resources, diagnostics - sandbox:browser_navigate # sandbox: exec, shell, web_fetch, web_search # sandbox: browser_navigate, browser_observe, browser_screenshot, # browser_content, browser_click, browser_type, browser_evaluate # sandbox: vision_screenshot, vision_navigate, vision_click, # vision_type, vision_scroll, vision_key, vision_drag # (requires EXPERIMENTAL_VISION=true) # sandbox: file_read, file_write, file_edit, file_insert, file_replace_lines # builtin: ask_user, save_memory, canvas_write, canvas_append, generate_image, generate_tts, generate_video # generate_video: distributed video generation via P2P (requires P2P enabled) # (conditional: integration_post, integration_context, email_send) skills: - skill-name # or use mode: all to attach all skills output: format: text # text | structured memory: enabled: true maxLines: 100 integrations: - type: collabnook url: "wss://collabnook.com/ws" # optional — defaults to wss://collabnook.com/ws channel: general botName: Bot - type: email imap: host: imap.gmail.com port: 993 smtp: host: smtp.gmail.com port: 587 auth: user: agent@example.com pass: pw pollInterval: 60 folder: INBOX triggers: - type: cron schedule: "*/5 * * * *" input: query: "Task" publish: true # or { enabled: true, password: "secret" } p2p: # P2P network config share: true # share this agent on the P2P network leverage: false # P2P model fallback — if a model (LLM, image, TTS) isn't available locally, search peers by name sampleQuestions: # optional — clickable chips shown in chat UI on initial load - "What can you help me with?" - "Summarize the latest report" ``` Published agents are accessible at `/chat/<agent-name>` with optional per-agent password. Agents with `p2p.share: true` are shared on the P2P network (enabled by default). Agents with `p2p.leverage: true` get P2P model fallback — if a model (LLM, image, or TTS) isn't available locally, the agent searches P2P peers by model name. This is different from `model: p2p` which explicitly routes LLM calls to a remote peer. P2P settings (peer name, network key, rate limit) are configurable in the P2P tab UI or via environment variables. ## Step-Based Workflows (`workflows/<name>.workflow.yaml`) ```yaml name: my-workflow description: What the workflow does type: steps input: schema: query: type: string required: true steps: - id: step-one agent: agent-name input: query: "{{query}}" output: key: step_one_result extract: output - id: step-two agent: another-agent input: query: "{{step_one_result}}" output: key: step_two_result condition: "{{step_one_result}}" - parallel: - id: branch-a agent: agent-a input: query: "{{query}}" output: key: result_a - id: branch-b agent: agent-b input: query: "{{query}}" output: key: result_b config: timeout: 300000 onError: stop # stop | continue | retry output: result: "{{step_two_result}}" chatOutputFormat: text # text | json sampleQuestions: - "Run the pipeline" ``` ## ReAct Workflows (`workflows/<name>.workflow.yaml`) ```yaml name: my-react-workflow description: Autonomous workflow with tool and agent discovery type: react input: schema: query: type: string required: true prompt: system: | You are a helpful assistant. goal: "Answer the user's query" graph: model: default tools: sources: - mcp - knowledge - function - builtin mode: all # all | none | include | exclude exclude: - dangerous_tool agents: mode: all exclude: - architect executionMode: react # react | single-turn maxIterations: 10 timeout: 300000 output: result: "{{result}}" chatOutputFormat: text # text | json sampleQuestions: - "What can you do?" ``` ## Knowledge Stores (`knowledge/<name>.knowledge.yaml`) ```yaml name: my-knowledge description: What this store contains source: type: directory # directory | file | database | web path: ./docs pattern: "**/*.md" # Web-specific: url, selector (html only), headers, jsonPath (dot-notation for nested arrays) loader: # optional — defaults: html (web), text (file/directory) type: text # text | pdf | csv | json | markdown | html splitter: type: recursive # character | recursive | token | markdown chunkSize: 1000 chunkOverlap: 200 embedding: default # reference to models.yaml config search: defaultK: 4 scoreThreshold: 0.5 reindex: # optional — periodic refresh schedule: "0 * * * *" # cron expression graph: # optional — works with database, csv, json (array of objects) directMapping: entities: - type: Person idColumn: id nameColumn: name properties: - email - role: job_title relationships: - type: WORKS_FOR source: Person target: Organization sourceIdColumn: person_id targetIdColumn: org_id ``` Web sources support all loader types. Use `loader.type: json` for APIs, `text` for raw content, `html` (default) for web pages with optional `selector`. Add `headers` for authenticated endpoints. Use `jsonPath` (e.g., `items` or `data.results`) to extract a nested array from the JSON response before parsing. ## Custom Functions (`functions/<name>.function.mjs`) ```javascript export const metadata = { name: "my-function", description: "What it does" }; export const parameters = { type: "object", properties: { input: { type: "string", description: "Input" } }, required: ["input"] }; export default async function({ input }) { return { result: `Processed: ${input}` }; } ``` Function parameters support automatic type coercion — if an LLM passes a number as a string, it is auto-coerced to the declared type. ## Skills (`skills/<name>/SKILL.md`) Markdown files with YAML frontmatter (`name`, `description`). Content is injected into the agent's system prompt. Add `sandbox: true` if the skill requires sandbox tools. ## MCP Servers (`mcp.json`) ```json { "servers": { "name": { "url": "https://example.com/mcp", "enabled": true } } } ``` Remote: `url`. Local: `command` + `args`. Optional: `headers`, `env`, `timeout`, `transport`, `description`. Transport is auto-detected. To add a server: read `mcp.json`, add entry, write back, then reference as `mcp:<name>` in agent tools. ## Model Configuration (`models.yaml`) ```yaml version: "1.0" llm: default: omni omni: provider: omni model: gemma-4-E2B-it-IQ4_NL reasoningBudget: 0 contextSize: 32768 active: true share: true lmstudio: provider: local engine: lmstudio baseUrl: http://localhost:1234/v1 model: qwen3.5-4b-mlx active: false openai: provider: openai apiKey: ${OPENAI_API_KEY} model: gpt-4.1 active: false embeddings: default: omni omni: provider: omni model: nomic-embed-text-v1.5.Q4_K_M image: default: omni omni: modelPath: .models/flux2-klein/flux-2-klein-4b-Q4_K_M.gguf llm: .models/flux2-klein/Qwen3-4B-Q4_K_M.gguf vae: .models/flux2-klein/flux2-vae.safetensors steps: 20 description: flux2-klein share: true tts: default: omni omni: modelPath: .models/qwen3-tts description: Qwen3 TTS 0.6B share: true ``` The `default` key is a string pointer to another config name. Providers: `omni`, `local`, `openai`, `anthropic`, `gemini`. Use `reasoningBudget`/`thinkingBudget` for thinking models. Use `share: true` to share a model on the P2P network. Values support `${ENV_VAR}` substitution. ## Environment Variable Substitution All YAML and JSON config files support `${ENV_VAR}` and `${ENV_VAR:-default}` syntax. Use this for secrets, URLs, and any values that differ between environments. ## Best Practices - Use kebab-case for all resource names - Temperature: 0.0-0.3 for structured tasks, 0.5-0.7 for creative - Only include tools the agent actually needs - Always read existing resources before modifying them - Check `workspace_list_resources` before creating to avoid name collisions - Use skills to share knowledge across agents without duplicating prompts