Run your first agent on Aex

1. Get your keys

Use Node.js 24 and an OpenAI API key. Sign in to the dashboard, create an Aex API key, and save it when shown. Keep both keys on your backend. Your model provider bills inference separately.

export AEX_API_KEY="your-aex-key"
export OPENAI_API_KEY="your-openai-key"

2. Install

npm install @aexhq/sdk@1.0.0

3. Run an agent

Save this as order.mjs, then run node order.mjs. The harness runs on Aex; the lookup runs in your connected application.

import { Aex, ApiKey, Model, Tool } from "@aexhq/sdk";

const aex = new Aex({ apiKey: process.env.AEX_API_KEY, maxCostMicroUsd: 1000000 });
try {
  const session = await aex.sessions.create({
    harness: "pi",
    model: Model("openai/gpt-4.1-mini", ApiKey(process.env.OPENAI_API_KEY)),
    tools: [Tool({
      name: "lookup_order",
      description: "Look up an order by id",
      input_schema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
      run: ({ id }) => ({ id, status: "shipped" }),
    })],
  });
  console.log((await session.send("Look up order A-1001. Has it shipped?")).output);
  console.log("Session:", session.id);
} finally {
  await aex.close();
}

Closing the client disconnects callbacks and keeps the session. Save its ID and use aex.sessions.get(id) later. Explicitly rebind callbacks with session.rebind(tools) after reconnecting. session.close() keeps history; session.delete() waits for hosted cleanup before removing content.

Choose a harness and tools

Select pi, codex or opencode as the harness. Aex installs and manages their native runtimes. Tool({ run }) functions stay in their declaring process.

• Application endpoints keep tools available after the SDK caller exits.
• Attached browser tabs run DOM callbacks after an explicit user gesture.
• Managed tools provide authorized sandboxes, remote browsers and session inspection.
• Owned images and PDFs reach all three native harnesses.

submit() returns acceptance. send() waits for a completed turn and returns its output, events and session. History cursors are opaque strings. An uncertain action is never silently replayed.

Structured output

Install Zod 4.4.3 and validate the assistant answer locally:

import { z } from "zod";
const answer = await session.send("Return the order status", {
  output: { type: z.object({ id: z.string(), status: z.string() }), maxRetries: 2 },
});
console.log(answer.status);

The return type follows the schema. Invalid JSON or schema issues can trigger up to two additional correction turns by default. Zero retries validates one answer. Each correction is visible in history and can incur model and hosting charges. Provider failures and missing answers fail explicitly. Exhaustion throws StructuredOutputError.

Keep the caller connected and sends exclusive during validation. An abort signal stops further corrections. Reusing an unchanged idempotency key reads completed receipts without repeating work. See the SDK guide.

Use the CLI

npm install -g @aexhq/cli@1.0.0
aex login
aex keys create "My application"
aex usage

Hosting prices and limits

Model hosting is offered at $0.22 per million input + output tokens. Managed compute, attachment storage and downloads have separate prices. Your model-provider bill remains separate.

The dashboard shows your exact offered and accepted prices. Accept prices and fund required prepaid resources before work. Set a monthly spending limit; there are no automatic topups. The example sets a 1 USD hosting ceiling, not a price or a cap on provider charges.

Aex is in early preview. Maintenance can interrupt work; retained history and explicit unknown usage support recovery. See the billing guide.