No. Use Core and Integrations for how-to. This page is the package map for @monorch/ai.

Where are openai() and postgres adapters documented?

Sibling Reference pages for @monorch/ai/openai and @monorch/ai/postgres. Error codes have their own Reference page.

Do I import @monorch/runtime directly?

Almost never. @monorch/ai loads it. See the runtime reference if you are debugging the FFI.

`@monorch/ai`

Sole user-facing TypeScript API. Agents, tools, graphs, memory helpers, MCP bridges, events, and errors. For the supported contract and SemVer rules, start with Public API. Guides under Core / Integrations own the tutorials; this page is the package map.

Install

shell

bash

pnpm add @monorch/ai
# peer: zod; native: @monorch/runtime (workspace / published platform package)

Constructors

tool(def): Register a Zod-validated tool. Also toolWithIr + jsonSchemaToIr when you already have JSON Schema (see Tools).
agent(options): Create/register an agent. Methods: run, stream, handoff.
graph(name): Graph builder. Prefer over workflow().
workflow(name?): Linear sugar over graph(). Prefer graph() for new code. maxRetries is a no-op; use maxSteps.
model(provider): Handle with generate / stream / generateObject.
openai / mock: Re-exported from @monorch/ai/openai for convenience.

Helpers

getAgent(name): Process agent registry lookup.
callTool / listTools: Execute or list registered tools.
memorySaver(): In-process checkpointer.
inMemoryStore / inMemoryThreads: Process-local helpers. Store is BYO from nodes/tools; threads wire into agent.run via threadId + memory.
mcpTools / mockMcp / mcpStdio / mcpHttp: MCP → tool(). See MCP.
jsonSchemaToIr / zodToIr: Schema IR for Rust validation.
createOtelListener / tapEvents / collectEvents: Observability and test helpers on AiEvent.
getRuntime(): Native Engine escape hatch.
AiError: Typed error with code.

Graph builder API

.node / .agentNode / .interrupt / .edge / .compile: Define and register a graph. Compile options: checkpointer?, maxSteps?, replace?.
start / restore / drive / resume / stream / checkpoint: Compiled graph and run-handle methods.
GRAPH_END: Constant "__end__" edge target.

Keywords

GraphRunStatus

pending, running, waitingInterrupt, needsRoute, completed, failed. Workflows use the same status strings as graphs (waitingInterrupt).

run_end.status

completed, failed, handed_off, aborted, waitingInterrupt.

AiEvent.type

events.ts

typescript

run_start | text | tool_call | tool_result
| node_start | node_end | interrupt | handoff
| error | run_end

Option keys

AgentOptions: name?, model, instructions?, tools?, handoffs?, maxSteps?, onEvent?
AgentRunOptions: threadId?, memory?, signal?
ToolDefinition: name, description?, input, permission? (allow | deny | roles), execute
ToolPermission: { type: "allow" }, { type: "deny" }, or { type: "roles", roles: string[] }

Common AiError codes

ABORTED, AGENT_FAILED, AGENT_MISSING, HANDOFF_DENIED, TOOL_PREPARE_FAILED, GRAPH_FAILED, GRAPH_ROUTE, CHECKPOINT_NOT_FOUND, VALIDATION_FAILED, NODE_MISSING. Full catalog and recovery: Errors & failure modes.

@monorch/ai