Build your first Agent

Build a durable Agent from Constal’s seven primitives, then package, deploy, and invoke it.

Every Constal Agent is composed from turn, ledger, commit, await, spawn, map, and reduce. This first Agent introduces turn; the runtime commits the returned result as durable truth. Add ledger when prior history should shape the next decision. Learn the Agent language, or choose a production shape from the Agent patterns catalog.

1. Create the Agent

shell

npm install @constal/sdk

src/index.ts

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

export default agent({
  id: "helpful-assistant",
  version: "1.0.0",
  model: "model",
  async onMessage(message, ctx) {
    const turn = await ctx.turn({
      system: "Resolve the request accurately and concisely.",
      objective: message,
    });
    return turn.message.content;
  },
});

Commit the generated dependency lockfile and add a constal.agent.json manifest whose entry points to this file. Archives contain one manifest, package.json, the lockfile, and source; lifecycle scripts and development dependencies are rejected.

2. Upload an immutable deployment

shell

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

Poll GET /v1/deployments/:id. A successful build publishes a pinned executable artifact and immutable deployment revision.

3. Dispatch an event

shell

curl https://platform.constal.ai/v1/events \
 -H "Authorization: Bearer $CONSTAL_API_KEY" \
 -H "Content-Type: application/json" --data '{
 "v":1,"id":"message-1","type":"message",
 "target":"crn:constal:production:default:default:agent/helpful-assistant",
 "session":"first-session","data":{"message":"Hello"}}'