# Create your first agent

Create your first OrchaJS agent, call .run(), and read the result, stream, and session ID.

Source: https://orcha.sh/docs/first-agent
Markdown: https://orcha.sh/docs/first-agent.mdx

An agent is a folder with model configuration and instructions.

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

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

## Configure the agent

`orcha/exampleAgent/index.json`:

```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 instructions

`orcha/exampleAgent/instructions.md`:

```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 it

`orcha/index.ts`:

```ts

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

The registration key becomes the runtime property
`orcha.exampleAgent`.

## Run it from code

```ts

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 reference

`run()` accepts a string or an input object.

### Text

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

The equivalent text block is:

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

### Local file

```ts
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:

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

### Remote URL

```ts
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 fields

```ts
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()` returns

`run()` returns an execution handle immediately:

```ts
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 output

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

```ts
const result = await execution.result;

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

### JSON output

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

```ts
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 states

```ts
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 →](/docs/multimodal)