Skip to content

INTEGRATOR_SCOPE.md

Latest commit

 

History

History
96 lines (67 loc) · 4.03 KB

INTEGRATOR_SCOPE.md

File metadata and controls

96 lines (67 loc) · 4.03 KB
Raw

Integrator scope vs platform operator

Genetic tag: repo.platform.sdk.integrator_scope.gen1
RU: INTEGRATOR_SCOPE_ru.md
Audience: npm consumers (@agentstack/sdk), third-party agents, tenant-hosted apps.

AgentStack distinguishes two SDK audiences:

Audience SDKConfig.sdkAudience Admin surfaces
Tenant integrator (default) integrator or omitted Blocked
Ecosystem operator platform_operator Allowed (monorepo SPA / ops only)

Ecosystem admin (/api/admin/*, sdk.admin, sdk.platform.adminData, protocol *AdminExecute) is for AgentStack operators running the platform control plane—not for applications built on AgentStack by customers.

Platform substrate: Core and @agentstack/sdk must not hardcode tenant flagship PIDs or product brands — see PLATFORM_SUBSTRATE_NO_TENANT_CODE.md (repo.engineering.platform_substrate_no_tenant_code.gen1).

What integrators should use instead

Need Use
Project CRUD, members sdk.platform.api
8DNA tables sdk.platform.dna, sdk.platform.projects, sdk.platform.users
Commands + snapshots sdk.platform.protocol
Roles in a project sdk.platform.rbac
AgentNet economy (tenant) sdk.platform.economy → /api/agentnet/{project_id}/*
Agents in a project sdk.agentsFleet
Support inbox sdk.support
Social / messenger (tenant) sdk.platform.social, sdk.createMessengerEmbed()

Never call /api/admin/* from tenant code. The HTTP client rejects those paths when sdkAudience is integrator.

Runtime guards (TypeScript)

  1. sdk.admin, sdk.adminData, sdk.platform.adminData — throw AgentStackError for integrators.
  2. HTTPClient.request — blocks paths containing /admin/ for integrators (defense in depth).
  3. sdk.platform.protocol.socialAdminExecute / agentsAdminExecute — operator-only.
  4. getModuleCatalog() / getCapabilityMatrix() — omit admin and adminData for integrators so AI discovery does not suggest them.

Monorepo frontend sets sdkAudience: 'platform_operator' in shared/sdk-client.ts.

API base URL

Surface Production
REST https://agentstack.tech/api
OpenAPI https://agentstack.tech/swagger
MCP https://agentstack.tech/mcp

Do not use legacy hosts (api.agentstack.com, api.agentstack.tech, docs.agentstack.com). Node/scripts: AGENTSTACK_API_BASE=https://agentstack.tech/api or omit and call resolveAgentStackApiBase().

Channel decision (MCP vs REST vs OpenAPI)

Need Prefer Notes
New agent / automation integrations MCP agentstack.execute Discovery: GET /mcp/actions
Project/user key-value data 8DNA GET/POST /api/dna/data or MCP projects.update_project Universal channel
Typed SPA / SDK REST already in use REST /api/* Marked x-channel: rest_compat in OpenAPI
Contract / codegen / explorer OpenAPI /openapi.json, /docs, /api-docs Gene docs.api.specs.gen1

See API_CHANNELS_AND_PROTOCOLS.md and OPENAPI.md.

Configuration

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

// Default — tenant / npm integrator (no admin)
const appSdk = new AgentStackSDK({
  apiBase: resolveAgentStackApiBase(),
  projectId: 42,
});

// AgentStack monorepo ops shell only
const opsSdk = new AgentStackSDK({
  apiBase: resolveAgentStackApiBase(),
  projectId: 1,
  sdkAudience: 'platform_operator',
});

Discovery for AI agents

After sdk.getModuleCatalog(), integrators will not see admin or adminData entries. If an agent still tries sdk.admin, the error message points here.

See also: AGENTS.md, docs/SDK_AI_SURFACE.md (monorepo).