Build AI Apps — Getting Started

Overview

Build self-contained AI-powered applications where agents handle core workflows inside your product. Think personal assistants, financial advisors, customer support products, or any app with AI at the center.

This guide walks you through creating your first app, installing the SDK, and running a working agent.

---

1. Create an app and keys

Go to developers.archastro.ai and create a new app. Every resource you create (agents, threads, configs, webhooks) is scoped to an app.

Once your app is created, generate two API keys:

Key type	Prefix	Where to use it
Publishable	pk_live_	Client-side code, SDK initialization
Secret	sk_live_	Server-side only — never expose in browser code

The secret key is shown once at creation. Copy it immediately and store it securely.

---

2. Install the SDK

npm install @archastro/sdk

For Next.js applications with server-side auth:

npm install @archastro/sdk-nextjs

---

3. Initialize the client

Create a server-side client with your secret key. This client can create agents, manage routines, read threads, and call any API endpoint.

import { ArchAstroClient } from "@archastro/sdk";

const client = new ArchAstroClient({
  baseURL: "https://api.archastro.ai",
  secretKey: process.env.ARCHASTRO_SECRET_KEY!,
});

// Wait for auth to hydrate before making calls
await client.ready;

For client-side code (browser), use the publishable key instead:

const client = new ArchAstroClient({
  baseURL: "https://api.archastro.ai",
  publishableKey: process.env.NEXT_PUBLIC_ARCHASTRO_PK!,
  storageStrategy: "secure", // encrypts tokens in localStorage
});

---

4. Create an agent

An agent is a persistent identity that can participate in conversations, execute routines, and access external data through installations.

const agent = await client.rest.createAgent({
  name: "Support Agent",
  metadata: {
    department: "customer-success",
  },
});

console.log("Agent created:", agent.id); // agi_abc123

Agents have their own ID prefix (agi_), and every agent gets a dedicated encrypted credential store for scoped secrets.

---

5. Attach a routine

Routines are event-driven behaviors. When a matching event fires, the routine executes a workflow, script, or preset handler.

const routine = await client.rest.createAgentRoutine({
  agent_id: agent.id,
  name: "billing_triage",
  event_type: "thread.message_added",
  handler_type: "script",
  script: `
    const message = event.payload.message;
    if (message.text.includes("invoice")) {
      return { route: "billing", priority: "high" };
    }
    return { route: "general" };
  `,
});

console.log("Routine created:", routine.id); // arn_xyz789

Routines start in draft status. Activate them to start processing events:

// Via the developer portal or API
await client.rest.activateAgentRoutine(routine.id);

---

6. Create a thread and send messages

Threads are conversations. They can be owned by a user or a team, and agents can participate as members.

// Create a thread
const thread = await client.rest.createThread(teamId, "Billing support");

// Join via real-time WebSocket
import { ChatRoomService } from "@archastro/sdk";

const chat = new ChatRoomService(client.socket);
const room = await chat.joinThread(teamId, thread.id);

// Send a message
await room.postMessage("I need help with invoice INV-2041");

// Listen for responses (including agent responses)
room.on("message_added", (event) => {
  console.log(`[${event.message.actor.name}] ${event.message.content}`);
});

Real-time communication uses WebSocket channels. The SDK handles connection management, reconnection, and token refresh automatically.

---

Fastest start: use your coding agent

If you use Claude Code, Codex, or Gemini CLI, paste this prompt in your project root:

Set up ArchAstro agent-first scaffolding in this repo.

1) Install:
   npm i @archastro/sdk

2) Create:
   - src/lib/archastro.ts (client initialization)
   - src/agents/bootstrap-support-agent.ts

3) In bootstrap-support-agent.ts:
   - create one agent via client.rest.createAgent(...)
   - create one routine via client.rest.createAgentRoutine(...)
   - print created IDs

4) Add npm script:
   "archastro:bootstrap-agent": "tsx src/agents/bootstrap-support-agent.ts"

Use env vars:
ARCHASTRO_SECRET_KEY
ARCHASTRO_APP_ID (if calling developer endpoints)

---

SDK vs CLI

Approach	Best for	Install
SDK (recommended)	Code-level control, building product features	npm install @archastro/sdk
CLI	App bootstrap, operational commands, CI/CD	npm install -g @archastro/developer-platform-cli

The CLI uses a verb-first syntax (archastro create agent, archastro list threads) and supports --json output for scripting. See the CLI reference for the full command set.

---

Environment variables

Variable	Required	Purpose
ARCHASTRO_SECRET_KEY	Yes (server)	Server-side API authentication
ARCHASTRO_APP_ID	For developer endpoints	App-scoped control-plane operations
NEXT_PUBLIC_ARCHASTRO_PK	For client-side	Browser SDK initialization
SESSION_SECRET	For Next.js SDK	Session encryption

---

What to build next

Now that you have a working agent with a routine, here's how to expand:

1. Add agent memory — give your agent persistent memory across sessions. See Agent Memory.
2. Build an agent network — connect multiple agents that collaborate through teams. See Agent Network.
3. Enable computer use — let agents provision machines and execute commands. See Computer Use.
4. Add installations — connect your agent to Gmail, GitHub, Slack, or custom data sources. See Agents.
5. Configure the portal — manage agents, routines, configs, and webhooks visually. See Developer Portal.
6. Build workflows — compose multi-step execution flows. See Workflows.
7. Go to production — review the production checklist.

---

Production checklist

Before deploying agents to production:

1. Keep sk_* keys server-only. Rotate keys if compromised.
2. Use least-privilege OAuth scopes on installations.
3. Gate side-effectful agent actions behind explicit approval routines.
4. Monitor routine executions via the portal or automations API.
5. Test new routines in a sandbox before activating in production.
6. Add regression tests for auth, agent CRUD, routine activation, and critical thread flows.