Create your first agent

An agent is a folder with model configuration and instructions.

orcha/
  index.ts
  exampleAgent/
    index.json
    instructions.md

If you ran npx orcha init, these files already exist.

Configure the agentCopy Anchor Link

orcha/exampleAgent/index.json:

{
  "name": "Example Agent",
  "description": "Answer general questions clearly and concisely.",
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "region": "provider_managed",
  "maxTokens": 10240,
  "outputType": "text"
}

Write its instructionsCopy Anchor Link

orcha/exampleAgent/instructions.md:

You are a concise and helpful assistant.

Answer the user's question directly before adding supporting detail.
Use clear language and practical examples.
Ask one focused question when the request is ambiguous.
Separate established facts from assumptions.
If you are uncertain, say so instead of inventing an answer.

Register itCopy Anchor Link

orcha/index.ts:

import { orcha } from "orchajs";

orcha.init({
  providers: {
    anthropic: process.env.ANTHROPIC_API_KEY ?? "",
  },
  agents: {
    exampleAgent: "./exampleAgent",
  },
});

The registration key becomes the runtime property orcha.exampleAgent.

Run it from codeCopy Anchor Link

import "./orcha/index.js";
import { orcha } from "orchajs";

const agent = orcha.exampleAgent;
const execution = agent.run("What is an idempotent API?");
const result = await execution.result;

if (result.status === "completed") {
  console.log(result.output);
}

Every call to run() creates a new durable session.

Input referenceCopy Anchor Link

run() accepts a string or an input object.

TextCopy Anchor Link

agent.run("Explain durable sessions.");

The equivalent text block is:

agent.run({
  content: {
    type: "text",
    text: "Explain durable sessions.",
  },
});

Local fileCopy Anchor Link

agent.run({
  content: [
    { type: "text", text: "Summarize this document." },
    { filePath: "./documents/report.pdf" },
  ],
});

type: "file" is optional when filePath is present. Relative paths resolve from the Orcha project root. mimeType is inferred from the file extension when possible, or can be provided:

{
  type: "file",
  filePath: "./documents/report.bin",
  mimeType: "application/pdf",
}

Remote URLCopy Anchor Link

agent.run({
  content: [
    { type: "text", text: "Describe this image." },
    {
      url: "https://cdn.example.com/photo.jpg",
      mimeType: "image/jpeg",
    },
  ],
});

type: "url" is optional when url is present.

Use url for any remote image, document, audio, or video. mimeType tells Orcha what the resource contains. Actual media support depends on the selected provider and model.

Additional input fieldsCopy Anchor Link

agent.run({
  content: "Help with account acct_123.",
  name: "Account support",
  metadata: {
    accountId: "acct_123",
  },
  variables: {
    companyName: "Acme",
  },
  clientCapabilities: [
    "request_human_approval",
  ],
});

• name is an optional session label.
• metadata stores durable application context.
• variables replace {{ variableName }} placeholders in instructions.
• clientCapabilities lists client actions available to this caller.

What run() returnsCopy Anchor Link

run() returns an execution handle immediately:

const {
  sessionId,
  stream,
  result,
  snapshot,
  evaluations,
} = agent.run("Hello");

• sessionId is available immediately.
• stream is a ReadableStream of cumulative execution snapshots.
• result is a promise for the final run result.
• snapshot is the latest snapshot, or undefined before the first update.
• evaluations is a promise for asynchronous evaluation results.

Await result first. On the resolved run result, result.output is the agent's final output, as shown below.

Text outputCopy Anchor Link

For an agent configured with "outputType": "text", result.output is a string:

const result = await execution.result;

if (result.status === "completed") {
  console.log(result.output); // string
}

JSON outputCopy Anchor Link

For an agent configured with "outputType": "json", result.output is the object defined by the agent's outputSchema:

const result = await execution.result;

if (result.status === "completed") {
  console.log(result.output); // validated JSON object
}

Text and JSON use the same result.output property. The difference comes from the agent configuration, not from a different execution field.

Result statesCopy Anchor Link

const result = await execution.result;

result.status is one of:

• completed — contains output and optional usage.
• waiting_for_client_action — contains clientToolCalls.
• paused — the execution stopped and can be resumed.
• failed — contains a structured error.

Every result includes sessionId. Save it when the conversation may continue later with agent.resume(sessionId, ...).

Read the complete multimodal reference →