Build and run your first agent

Bring up the local Nexis stack, authenticate a client, create a durable run, and confirm that the ManagerAgent delegated work to a specialist and finished. Prerequisites: Node.js 22, pnpm 10, and Docker for the local data plane.

1. 1

   Check the environment

   The doctor reports missing tools and keys without printing secret values.

   $ node scripts/setup-agent-local-env.mjs --strict
2. 2

   Install dependencies

   Enable Corepack, then install the exact lockfile.

   $ corepack enable && pnpm install --frozen-lockfile
3. 3

   Start the data plane

   Postgres holds durable platform state; Redis handles locks, fanout, and rate limits.

   $ docker compose -f docker-compose.dev.yml up -d postgres redis
4. 4

   Start Nexis

   Launch agent-runtime, tool-gateway, the API BFF, and the web app together.

   $ pnpm dev:ai:local
5. 5

   Confirm health

   Run the checker from a second terminal once the app is reachable at 127.0.0.1:3120.

   $ pnpm dev:ai:local:check

Authenticate the client

import { AgentPlatformClient } from '@agent-platform/client-sdk';const client = new AgentPlatformClient({  baseUrl: 'http://localhost:3110',  getAccessToken: () => session.access_token,});const profile = await client.getProfile();

Create the run

const run = await client.createRun({  prompt: 'Research Base liquidity and produce a report',  idempotencyKey: crypto.randomUUID(),});console.log(run.runId);

ManagerAgent owns your run and calls bounded specialists as tools: ResearchAgent for read-only web and connector lookups here, with RiskAgent evaluating any tool call that carries write, financial, or irreversible risk before it executes.

Confirm completion

const res = await fetch(  `http://localhost:3110/v1/runs/${run.runId}`,  { headers: { authorization: `Bearer ${session.access_token}` } },);const state = await res.json();

• GET /v1/runs/{run_id}/artifacts lists anything the run produced, once you are ready to collect outputs.
• Every tool ManagerAgent calls declares a risk tier, required scopes, and an audit event. Nothing runs unclassified.