For Coding Agents

Overview

This page is designed for AI coding agents. It provides everything you need to scaffold, build, and operate ArchAstro-powered applications without ambiguity.

---

Quick setup prompt

Paste this into your project root to bootstrap an ArchAstro agent scaffold:

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 src/lib/archastro.ts:
   import { ArchAstroClient } from "@archastro/sdk";
   export const client = new ArchAstroClient({
     baseURL: "https://api.archastro.ai",
     secretKey: process.env.ARCHASTRO_SECRET_KEY!,
   });

4) In bootstrap-support-agent.ts:
   - import { client } from "../lib/archastro"
   - await client.ready
   - create one agent via client.rest.createAgent({ name: "Support Agent" })
   - create one routine via client.rest.createAgentRoutine({
       agent_id: agent.id,
       name: "handler",
       event_type: "thread.message_added",
       handler_type: "script",
       script: "return { handled: true };"
     })
   - print created IDs
   - call client.dispose()

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

Use env vars:
ARCHASTRO_SECRET_KEY (required)
ARCHASTRO_APP_ID (if calling reviewed developer endpoints under /protected/api/v2/developer/apps/:app_id/...)

---

Required environment variables

Before running any ArchAstro operations, check that these are set. Ask the user for values you don't have.

Variable	Required	Purpose
ARCHASTRO_SECRET_KEY	Always	Server-side API authentication (sk_live_ prefix)
ARCHASTRO_APP_ID	For developer endpoints	App-scoped control-plane operations
NEXT_PUBLIC_ARCHASTRO_PK	Client-side only	Browser SDK initialization (pk_live_ prefix)
SESSION_SECRET	Next.js SDK only	Session encryption key

Do not proceed with write operations without confirming these values exist.

---

Canonical URLs

Resource	URL
API base	https://api.archastro.ai
Developer portal	https://developers.archastro.ai
Documentation	https://docs.archastro.ai
LLM index	https://docs.archastro.ai/llms.txt
Extended LLM index	https://docs.archastro.ai/llms-full.txt
OpenAPI spec	https://docs.archastro.ai/openapi.json

Treat these URLs as canonical. Do not infer or guess alternative endpoints.

---

SDK packages

npm install @archastro/sdk                    # core SDK (always required)
npm install @archastro/sdk-nextjs             # Next.js server helpers
npm install -g @archastro/developer-platform-cli  # CLI (optional)

The CLI currently requires GitHub Packages registry access:

# Add to ~/.npmrc
@archastro:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=GITHUB_TOKEN

---

Client initialization patterns

Server-side (secret key)

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

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

Client-side (publishable key)

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

BFF pattern (token provider)

const client = new ArchAstroClient({
  baseURL: "https://api.archastro.ai",
  publishableKey: "pk_live_...",
  tokenProvider: {
    async getTokens() {
      const res = await fetch("/api/auth/session", { credentials: "include" });
      return res.ok ? res.json() : null;
    },
    async onAuthExpired() {
      window.location.href = "/login";
    },
  },
});

---

Core SDK operations

Agents

const agent = await client.rest.createAgent({ name: "My Agent", lookup_key: "my-agent" });
const agents = await client.rest.listAgents();
await client.rest.updateAgent(agent.id, { name: "Updated" });
await client.rest.deleteAgent(agent.id);

Routines

const routine = await client.rest.createAgentRoutine({
  agent_id: agent.id,
  name: "handler",
  event_type: "thread.message_added",
  handler_type: "script",
  script: "return { handled: true };",
});

Threads and messages

const thread = await client.rest.createThread(teamId, "Title");
const messages = await client.rest.getThreadMessages(teamId, thread.id);

Real-time

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

const chat = new ChatRoomService(client.socket);
const room = await chat.joinThread(teamId, threadId);
room.on("message_added", (e) => console.log(e.message.content));
await room.postMessage("Hello");
await room.leave();

Networks (Agent Network)

// Teams and members
const team = await client.rest.createTeam({ name: "My Network" });
await client.rest.addTeamMember(team.id, { agent_id: agent.id, role: "member" });

// Participate routine (makes agent auto-respond)
await client.rest.createAgentRoutine({
  agent_id: agent.id,
  name: "participate",
  event_type: "thread.message_added",
  handler_type: "preset",
  preset_name: "participate",
});

// Cross-org networking (team invites)
const invite = await client.rest.createTeamInvite(team.id);
// Share invite.join_code with partner org
await client.rest.joinTeam(joinCode, { agent_id: partnerAgent.id });

// Team member management
const members = await client.rest.getTeamMembers(team.id);
await client.rest.removeTeamMember(memberId);

Connectors

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

const url = await buildConnectorAuthorizeUrl("google", {
  restApi: client.rest, teamId, accessLevel: "full_access",
  webRedirect: "https://app.example.com/callback",
});

Configs

const configs = await client.rest.listConfigs({ kind: "workflow" });
const validation = await client.rest.validateConfig({
  kind: "workflow", rawContent: yaml, mimeType: "application/x-yaml",
});

---

API scopes

Scope	Base path	Auth
Public auth	/api/v2/auth/..., /oauth/...	Publishable key or none
User runtime	reviewed /api/v2/users/... endpoints	JWT access token
Team runtime	reviewed /api/v2/teams/... endpoints	JWT access token
Developer	reviewed /protected/api/v2/developer/apps/:app_id/... endpoints	Secret key

Use /openapi.json for the exact currently published operations. Internal and private subtrees under those roots are intentionally omitted from the public docs artifact.

---

Resource IDs

Resource IDs use stable prefixed formats. In practice, external developers usually only need to know the resource type they are working with and pass IDs through SDK and API calls as returned by the platform.

---

Machine-readable indexes

• /llms.txt — lightweight page index for LLM context windows
• /llms-full.txt — extended index with full page content
• /openapi.json — OpenAPI 3.x specification

---

Rules for coding agents

1. Check env vars first — ask the user for ARCHASTRO_SECRET_KEY before any API calls
2. Use SDK methods — prefer client.rest.* over raw HTTP requests
3. Treat docs URLs as canonical — do not infer or construct endpoints
4. Check /openapi.json — for the latest endpoint signatures and types
5. Never expose secret keys — sk_live_ keys are server-only
6. Await client.ready — the client needs to hydrate auth before making calls
7. Dispose when done — call client.dispose() in scripts to clean up connections