Set up an SDK project

Create a minimal TypeScript package that the managed builder can validate, reproduce, and deploy.

Before you begin

Choose one package kind and obtain a deployment key. The archive contains source and immutable configuration only—never Credentials, .env, node_modules, generated output, or lifecycle scripts.

Steps

Install the SDK. The package manager records the resolved dependency in your lockfile:

npm install @constal/sdk

Add one root manifest:

constal.agent.json

{
  "schemaVersion": 2,
  "kind": "agent",
  "id": "support-agent",
  "namespace": "default",
  "version": "1.0.0",
  "entry": "src/index.ts",
  "mode": "script",
  "bindings": {
    "model": { "kind": "local", "resourceKind": "model", "id": "support" }
  },
  "policies": [],
  "tools": [],
  "limits": { "maxRunMicroUsd": 100000, "maxTurns": 8 }
}

Export the matching definition:

src/index.ts

import { agent } from "@constal/sdk";

export default agent({
  id: "support-agent", version: "1.0.0", model: "model",
  async onMessage(message, ctx) {
    const turn = await ctx.turn({ system: "Help the caller.", objective: message });
    return turn.message.content;
  },
});

Other root manifests are constal.channel.json, constal.auth-provider.json, constal.policy.json, constal.credential-provider.json, and constal.gateway.json. Identity, entrypoint, Resource bindings, and Policy attachments must agree with the exported definition.

Reusable packages use { "kind": "local", "resourceKind": <kind>, "id": <id> } for tenant-local bindings, Policies, and companion Resources. Deployment resolves those references inside the authenticated tenant and namespace and pins exact CRNs and hashes. Use an exact CRN only when the package intentionally depends on a platform-global or otherwise externally pinned Resource.

Package and upload:

zip -r support-agent.zip constal.agent.json package.json src
curl https://platform.constal.ai/v1/deployments \
  -H "Authorization: Bearer $CONSTAL_DEPLOYMENT_KEY" \
  -H "Idempotency-Key: support-agent-1.0.0" \
  -H "Content-Type: application/zip" \
  --data-binary @support-agent.zip

Verify

Poll GET /v1/deployments/:deploymentId. Success records the Resource identity, immutable deployment revision, executable artifact, code digest, and probe outcome. Confirm that version, bindings, and Policies match the archive. A public Git repository pinned to a full commit enters the same build path through the Console.

Next steps

Follow Build an Agent, Build a Channel and Auth Provider, Build a Credential Provider, or Build a custom Gateway. Use Deploy an Agent for the complete archive and release workflow.