Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (109 loc) · 6.53 KB

AGENTS.md

File metadata and controls

146 lines (109 loc) · 6.53 KB
Raw

AgentStack SDK — guide for AI agents

Genetic tag: repo.platform.sdk.ai_surface.gen1
RU: AGENTS_ru.md · Doc hub: docs/DOC_HUB.md · Glossary: docs/GLOSSARY.md
North star: fast, low-error construction of apps and sites on AgentStack via typed SDK + self-description.

60-second bootstrap

import { AgentStackSDK, resolveAgentStackApiBase } from '@agentstack/sdk';

const sdk = new AgentStackSDK({ apiBase: resolveAgentStackApiBase() });

// 1) Discover surfaces (read before calling APIs)
const catalog = sdk.getModuleCatalog();
const matrix = sdk.getCapabilityMatrix();

// 2) Auth — headless agent (preferred for scripts)
sdk.platform.auth.useApiKey(process.env.AGENTSTACK_API_KEY!, Number(process.env.AGENTSTACK_PROJECT_ID!));

// Human SPA alternative:
// await sdk.platform.auth.login({ email, password });

// 3) First REST call (projects) — or MCP via sdk.mcp.execute / CLI
const projects = await sdk.platform.api.getProjects();

15-line agent script (copy-paste):

import { AgentStackSDK, mcpExecute, resolveMcpUrl } from '@agentstack/sdk';
const apiKey = process.env.AGENTSTACK_API_KEY!;
const projectId = Number(process.env.AGENTSTACK_PROJECT_ID!);
const sdk = new AgentStackSDK({
  apiBase: 'https://agentstack.tech/api',
  apiKey,
  projectId,
});
sdk.platform.auth.useApiKey(apiKey, projectId);
const matrix = sdk.getCapabilityMatrix();
console.log('caps', matrix.platform?.length);
const discovery = await mcpExecute(
  [{ action: 'discovery.list', params: {} }],
  { token: apiKey, projectId, mcpUrl: resolveMcpUrl('https://agentstack.tech/api') },
);
console.log('tools', discovery);

Product CLI: npx @agentstack/cli — gene repo.tooling.user_cli.gen1 · docs/CLI_QUICKSTART.md

Previous human bootstrap (SPA):

await sdk.platform.auth.login({
  email: process.env.AGENTSTACK_EMAIL!,
  password: process.env.AGENTSTACK_PASSWORD!,
});

// 3) First REST call
const projects = await sdk.platform.api.getProjects();

// Project scope (X-Project-ID) — set projectId in config, after login, or updateProjectId:
sdk.updateProjectId(42);

Project context: docs/PROJECT_CONTEXT.md · sdk.getProjectId() · assertProjectIdConfigured(sdk)
How to install SDK (npm / submodule / monorepo): docs/SDK_INTEGRATION_FLOWS.md · RU: SDK_INTEGRATION_FLOWS_ru.md

Production API base: https://agentstack.tech/api (default via resolveAgentStackApiBase()).
Local Core: AGENTSTACK_API_BASE=http://localhost:8000/api
Vite apps: VITE_API_BASE_URL=https://agentstack.tech/api

Hosted workspace SaaS (/s/{pid}/{bucket}/)

Hosted buckets use workspace PID in session + POST /mcp (not /api/mcp/execute). Read integrator before editing hosted-vertical/ or hosted-sdk-cdn/:

Discover → validate → execute

Step API When
Discover sdk.getModuleCatalog() Pick module id, accessPaths, aiHints, examples
Gate sdk.getCapabilityMatrix() Skip disabled domain modules
Validate validateAppManifest(), assertIntegratorModule(), parseTaskManifest() Before writes
Execute sdk.platform.*, sdk.protocol.* REST + commands + snapshots
Deploy site sdk.hosting.quickStart() Static HTML hosting

Full recipes: docs/AI_APPLICATION_FACTORY.md

Decision tree

  • Agent script bootstrap → createAgentSession(config) → { sdk, catalog, matrix } then auth + first call
  • CRUD / projects / users → sdk.platform.api or sdk.platform.dna
  • DNA command bus → sdk.platform.protocol.executeCommand (not raw /commands fetch; prefer protocol over legacy sdk.protein.* for new code — docs/PROTEIN_SYSTEM_GUIDE.md)
  • Rules engine → sdk.platform.command or protocol.executeRulesCommand
  • Cached read model → sdk.platform.protocol.readThroughSnapshot
  • MCP automation → sdk.mcp.execute / mcpExecute() · subpath @agentstack/sdk/mcp · sdk.mcp.discoverByIntent() · sdk.mcp.getDiscovery() → JSON-RPC + REST discover (not protocol.execute)
  • Terminal / CI → @agentstack/cli (repo.tooling.user_cli.gen1) — curated SDK verbs + MCP escape hatch
  • Tenant apps → never sdk.admin / sdk.platform.adminData (docs/INTEGRATOR_SCOPE.md)

Genetic routing (hot paths)

Tag Doc / code
repo.platform.sdk.gen1 AI_INDEX.md
repo.platform.sdk.agent_protocol.gen1 ../docs/AGENT_PROTOCOL_QUICKSTART.md
repo.platform.sdk.ai_surface.gen1 ../docs/SDK_AI_SURFACE.md
repo.platform.app_manifest.gen1 @agentstack/sdk/manifest · appManifestSchema
sdk.capability_tasks.gen1 @agentstack/sdk/capability-tasks
sdk.hosting.gen2 sdk.hosting.quickStart
sdk.commerce.facade.gen1 sdk.commerce · @agentstack/sdk/commerce/*

Anti-patterns

  • Do not use fetch('/api/...') when sdk.platform or sdk.protocol exists.
  • Do not treat sdk.protocol.searchSnapshots as server full-text search (cache scan only).
  • Do not call sdk.projects.get(uuid) — projects is 8DNA DNATableWrapper; use sdk.platform.api.getProject(id).
  • Do not use sdk.admin or sdk.platform.adminData in tenant integrations (sdkAudience defaults to integrator).
  • Check getCapabilityMatrix() before calling optional domains (payments, gameData, …).

Links