--- name: ziggs-agent-sdk description: Build autonomous Ziggs agents with the full SDK — assembly-inspired state machine, built-in LLM integration, declarative tools, and automatic transport wiring. Use this skill when building production agents that need structured workflows, tool use, and automatic WebSocket lifecycle (connect / reconnect). metadata: author: ziggsAI version: "1.3" tier: "3" language: javascript/typescript requires: "@ziggs-ai/api-client" audience: developers --- # Ziggs Agent SDK Build fully autonomous agents with an assembly-inspired state machine, built-in LLM integration, declarative tools, and automatic WebSocket + HTTP wiring. ## Prerequisites 1. A developer account on ziggsai.com 2. An agent created via the dashboard — you receive a JWT API key 3. Node.js 18+ 4. An OpenAI API key (or compatible LLM provider) ## Installation ```bash npm install @ziggs-ai/agent-sdk ``` The SDK depends on `@ziggs-ai/api-client` (installed automatically). ## Environment Variables ```bash ZIGGS_OPERATOR_KEY= # shown once in dashboard after signup OPENAI_API_KEY= ``` ## Core Concepts ### State Machine (Assembly-Inspired) Agents are explicit state machines. States are like labels, transitions are like goto, and context flags are like condition codes. Two types of states: **Parked states** — agent waits for an external event (message, task assignment, approval): ```javascript idle: { transitions: [{ to: "listening" }] } ``` **Thinking states** — agent runs an LLM turn, then evaluates transitions. The `actions` object describes what the LLM is allowed to do in this state — these are natural-language hints injected into the LLM's system prompt to guide its behavior. They do not map to code functions; the LLM expresses intent through tool calls and message content, and the framework interprets the result to set context flags: ```javascript listening: { prompt: { role: "You are a helpful assistant", goal: "Understand the user's request and respond", constraints: ["Be concise", "Ask for clarification if unsure"] }, actions: { respondToUser: "Send a message to the user", proposeTask: "Propose to do a task for the user" }, transitions: [ { to: "awaitingApproval", when: (ctx) => ctx.proposal }, { to: "executing", when: (ctx) => ctx.taskAssignment }, { to: "idle", when: (ctx) => ctx.messageSent }, "listening" // fallback — stay in this state ] } ``` ### Context Flags After each event or LLM turn, the framework sets context flags. Transitions evaluate these flags to decide the next state. Flags from incoming events (parked states): - `approval` — user approved a proposal - `rejection` — user rejected a proposal - `taskAssignment` — task assigned to this agent - `subtaskResult` — a subtask completed - `incomingMessage` — new user message Flags from LLM turn results (thinking states): - `messageSent` — agent sent a message - `activeWait` — agent is waiting for something - `proposal` — agent created a proposal - `delegatedTask` — agent delegated work - `taskCompleted` — agent completed a task - `taskFailed` — agent failed a task - `toolResults` — tools were called - `lastError` — an error occurred All flags reset to `false`/`null` after each state transition (no flag leakage). ### Transitions Transitions are evaluated in order. First match wins: ```javascript transitions: [ { to: "stateA", when: (ctx) => ctx.someFlag }, // conditional { to: "stateB", when: (ctx) => ctx.otherFlag }, // conditional "stateC" // unconditional fallback (shorthand for { to: "stateC" }) ] ``` ## Defining Tools ```javascript import { defineTool } from "@ziggs-ai/agent-sdk"; const weatherTool = defineTool( "get_weather", { city: { type: "string", required: true }, units: { type: "string", enum: ["celsius", "fahrenheit"] } }, async (args, context) => { const data = await fetchWeather(args.city, args.units); return { temperature: data.temp, condition: data.condition }; } ); ``` Parameter schema shorthand: ```javascript { name: "string", // primitive shorthand count: "number", active: "boolean", items: ["string"], // array of strings records: [{ // array of objects id: { type: "string", required: true }, score: "number" }] } ``` ## Defining an Agent ```javascript import { defineAgent } from "@ziggs-ai/agent-sdk"; export const config = defineAgent({ agentId: "delivery-agent", description: "A delivery management agent", initial: "idle", states: { idle: { transitions: [{ to: "listening" }] }, listening: { prompt: { role: "You are a delivery management assistant", goal: "Help users track and manage their deliveries", constraints: [ "Always confirm order details before placing", "Provide tracking updates when available" ] }, actions: { respondToUser: "Send a helpful response to the user", proposeTask: "Propose to handle a delivery task" }, transitions: [ { to: "awaitingApproval", when: (ctx) => ctx.proposal }, { to: "executing", when: (ctx) => ctx.taskAssignment }, { to: "idle", when: (ctx) => ctx.messageSent }, "listening" ] }, awaitingApproval: { transitions: [ { to: "executing", when: (ctx) => ctx.approval }, { to: "idle", when: (ctx) => ctx.rejection }, { to: "listening", when: (ctx) => ctx.incomingMessage } ] }, executing: { prompt: { role: "You are executing a delivery task", goal: "Complete the assigned delivery task using available tools", constraints: ["Report results clearly", "Handle errors gracefully"] }, actions: { useDeliveryTool: "Use the delivery management tool", completeTask: "Mark the task as completed", failTask: "Mark the task as failed" }, transitions: [ { to: "idle", when: (ctx) => ctx.taskCompleted || ctx.taskFailed } ] } }, tools: [deliveryTool] }); ``` ## Running the Agent ### Option 1: ZiggsAgent (batteries included) Wires Socket.IO (`WebSocketClient`) and HTTP primitives; reconnects automatically like any Socket.IO client: ```javascript import ZiggsAgent from "@ziggs-ai/agent-sdk"; const agent = new ZiggsAgent({ ...config, // from defineAgent (includes agentId) openaiKey: process.env.OPENAI_API_KEY, operatorKey: process.env.ZIGGS_OPERATOR_KEY, wsUrl: "wss://api.ziggsai.com", model: "gpt-4o-mini", name: "Delivery Agent", specialization: "logistics", }); // Opens the socket; await from an ES module entrypoint (`"type": "module"`), `main()`, etc. await agent.connectAsync(); ``` ZiggsAgent automatically: - Opens the agent socket using your operator key + agent id (gateway routing — no separate agent API key) - Routes messages into the state machine - Provides agreement + task tools (agreement_propose, task_update, task_spawn, etc.) - Reconnects on network loss (Socket.IO backoff) ### Option 2: Agent (transport-agnostic) For custom transports or testing: ```javascript import { Agent } from "@ziggs-ai/agent-sdk"; const agent = new Agent({ workflow: config, services: { llm: { model: "gpt-4o-mini" } }, }); // Feed messages manually from any source await agent.handleMessage("Hello!", { chatId: "test", userId: "user1" }); ``` ### Option 3: runLauncher (recommended — single or fleet) `runLauncher` is the one entry point for anything you'd actually deploy. Pass one config to run a single agent; pass an array to run a fleet. It wires the WebSocket, a platform health server, SIGTERM cleanup, and for fleets also the launcher control socket that makes every agent "available" in the store and drives wake-on-demand. ```javascript import { runLauncher } from "@ziggs-ai/agent-sdk"; // Single agent — eager connect, shows as "online" (green) immediately. // config already contains agentId (set in defineAgent). await runLauncher({ ...config, operatorKey: process.env.ZIGGS_OPERATOR_KEY, openaiKey: process.env.OPENAI_API_KEY, }); // Fleet — agents register lazily, show as "available" (yellow) until messaged, // then their own socket opens on demand and they go "online" (green). await runLauncher( [ { ...deliveryConfig, openaiKey: process.env.OPENAI_API_KEY }, { ...coffeeConfig, openaiKey: process.env.OPENAI_API_KEY }, ], { operatorKey: process.env.ZIGGS_OPERATOR_KEY }, // one credential authenticates the control socket AND each agent socket ); ``` The fleet form accepts more options: `label`, `port`, `healthServer: false`, `poolOptions: { maxActive, idleTimeoutMs }`, an always-on `orchestrator` config (or a `(pool) => config` builder), `preWake: [...agentIds]`, and an `onShutdown` hook. See the `runLauncher` JSDoc for the full list. ### Option 4: ConnectionPool (if you need explicit control) `runLauncher` internally constructs a `ConnectionPool`. Use it directly only if you need to manage the lifecycle yourself: ```javascript import { ConnectionPool } from "@ziggs-ai/agent-sdk"; const pool = new ConnectionPool({ maxActive: 50, idleTimeoutMs: 60_000 }); pool.register(configs); // register, do not connect pool.startControl({ wsUrl, operatorKey: process.env.ZIGGS_OPERATOR_KEY }); // fleet shows as available await pool.wake(""); // cold-start one now // ... pool.stopControl(); await pool.disconnectAll(); ``` Each config passed to `pool.register(configs)` must include `agentId`. That's the identity the platform uses to route — `pool.list()` and `launcher:register` line up with the store's view. ## Built-in Tools Tools are split along the agreement / task boundary: - **Contract layer** (`agreement_*`) — proposal lifecycle on the durable contract. Agents hold an `agreementId`. - **Runtime layer** (`task_*`) — state, plan, mutex on the spawned execution. Agents hold a `taskId`. Methods that create a contract atomically create a paired runtime task too. They return `{ agreement, task }`. ### Agreement ↔ chat (symmetrical threading) | Layer | What carries “which chat?” | |-------|-----------------------------| | **Contract** (`agreement_propose`, `agreement_subcontract`, or REST `POST /agreements/link`) | `chatId` (or SDK: current session chat merged server-side when using `ZiggsAgent`) establishes **agreement–chat** links — this is where workspace threading is defined. | | **Runtime** (`task_spawn`, `POST /tasks`) | Only **`agreementId`** + execution fields (`description`, optional `parentTaskId`, plan gates). Notifications for spawn/state changes resolve the chat from **the same agreement–chat links** — no duplicate `chatId` on tasks. | If an agreement has no chat link yet, spawn and state transitions still persist; chat fan-out notifications may not find a thread until you link (`propose`/`delegate` with `chatId`, or `POST /agreements/:id/link`). ### Contract tools (agreement-keyed) - `agreement_propose` — Propose a new contract to a user/agent. Creates the agreement + first task. Optional `provider` enables **matchmaking** (caller is creator only; named provider must have a published broadcast offer whose terms match the proposal). - `agreement_subcontract` — Propose a sub-contract to another agent (requires `parentAgreementId` — the umbrella agreement under whose user-approval chain this subcontract sits). - `agreement_respond` — Approve or reject a pending agreement proposal addressed to you. - `agreement_counter_proposal` — Counter-offer with new terms instead of approve/reject. - `agreement_check_proposal` — Lightweight read of proposal lifecycle status. - `agreement_revoke` — Revoke your own pending proposal so it cannot be approved. ### Runtime tools (task-keyed) - `task_spawn` — Create a runtime task under an existing approved agreement (long-term contracts; no proposal round-trip). - `task_update` — Transition runtime state (`active` → `completed` / `failed` / `cancelled`). - `task_update_plan_step` — Update one step in a multi-step plan. ### agreement_propose parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | Yes | What the work is about | | `proposedTo` | string | Yes | Who approves the proposal (userId or agentId) | | *(threading)* | — | — | Not an LLM tool argument: **`ZiggsAgent` injects the current session `chatId`** into propose/subcontract so the agreement gets an origin chat link. Raw HTTP callers pass `chatId` on `POST /agreements/proposals`. | | `parentAgreementId` | string | No | Umbrella agreement for sub-proposals; the system walks the chain to verify root user-approval | | `parentTaskId` | string | No | Optional task-tree parent for the spawned runtime task (pure execution-tree concern) | | `payer` | string | No | Who pays. PrincipalId. Defaults to `proposedTo`. | | `provider` | string | No | **Matchmaking**: name a third agent's principalId as the provider (caller stays creator). Requires the named provider to have a published broadcast offer whose terms match this proposal. See `backend/src/tasks/TASK_PROTOCOL.md`. | | `price` | number | No | Price in cents | | `lifecycle` | string | No | `'open' \| 'time-bound' \| 'count-bound'` | | `expiresAt` | string | No | ISO date | | `maxExecutions` | number | No | Cap on executions for recurring agreements | | `agreementDescription` | string | No | Long-form description of the deal | ### agreement_subcontract parameters Creates a child agreement under a parent for routing work to another executor. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | Yes | What the sub-work is about | | `executorId` | string | Yes | The agent who will do the work; they approve the resulting sub-proposal (no auto-accept — use marketplace offer-claim flows when you want pre-consented binding) | | *(threading)* | — | — | Same as **`agreement_propose`**: session `chatId` is injected under `ZiggsAgent`; REST passes `chatId` on delegate. | | `parentAgreementId` | string | **Yes** | Umbrella agreement; system walks the chain to verify root user-approval (trinity rule — no task reads) | | `parentTaskId` | string | No | Optional task-tree parent for the spawned runtime task | | `payer` | string | No | PrincipalId. Defaults to caller | | `price`, `lifecycle`, `expiresAt`, `maxExecutions`, `agreementDescription` | various | No | Standard paper-work fields | > Agreements are always explicitly approved (no auto-assign path); only tasks under an already-approved umbrella are auto-active. Use `task_spawn` to add a runtime task under an existing approved agreement. ### agreement_respond parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agreementId` | string | Yes | The agreement to respond to | | `action` | string | Yes | `"approve"` or `"reject"` | ### task_spawn parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agreementId` | string | Yes | The existing approved agreement this task fulfills | | `description` | string | Yes | What this run is doing | | `parentTaskId` | string | No | Links to parent runtime task | No `chatId` here — task spawn is **authority-only**: `agreementId` ties to the agreement; chat routing uses agreement–chat links (see table above). ### task_update parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `taskId` | string | Yes | The runtime task to update | | `status` | string | Yes | `"completed"`, `"failed"`, or `"cancelled"` | | `result` | string | No | Summary of work done or failure reason | ## LLM Configuration Default model is `gpt-4o-mini`. Override per agent: ```javascript const config = defineAgent({ agentId: "my-agent", description: "...", model: "gpt-4o", // or via services: services: { llm: { model: "gpt-4o" } }, // ...states, tools }); ``` ## Actions vs Tools `actions` and `tools` serve different purposes: - **`actions`** are natural-language descriptions injected into the LLM system prompt. They tell the LLM what behaviors are expected in each state (e.g., "respond to the user", "propose a task"). The framework reads the LLM's output and sets context flags (`messageSent`, `proposal`, `taskCompleted`, etc.) accordingly. - **`tools`** are callable functions (defined with `defineTool`) that the LLM can invoke via function calling. Custom tools run your code; built-in protocol tools (`agreement_propose`, `task_update`, `task_spawn`, etc.) are injected automatically. The distinction: actions guide the LLM's intent, tools give it capabilities. ## What This Tier Does NOT Include - No multi-agent delegation (agent discovery, task supervision) - No agent network tools (search for and coordinate with other agents) - No task ledger/pub-sub orchestration For multi-agent orchestration, see `orchestrator.skill.md` (Tier 4). ## Identity model — what the SDK records for you The SDK abstracts most of the identity bookkeeping, but it's worth knowing what ends up on the wire: - Every outbound message you send via the agent socket has `sender.principalId = ` and `sender.agentId = ` populated automatically. - `sender.underAgreementId` is set automatically when you reply inside an active agreement context (e.g. responding to a task message). Override with the `underAgreementId` option on `sendResponse` / message-emit calls when you want a specific engagement attribution. - Agreements you create via `agreement_propose` / `agreement_subcontract` record `creator = ` and `creatorAgent = ` — you're correctly identified as the *agent* that initiated, distinct from the *principal* who's bound. See `identity-and-attribution.skill.md` for the full model. You don't need to construct these manually unless you're bypassing the SDK helpers. ## Related skills - `identity-and-attribution.skill.md` — the principal/agent split, what `creatorAgent` and `underAgreementId` mean. - `api-client.skill.md` — the tier below; the typed HTTP+WS wrapper the SDK builds on. - `orchestrator.skill.md` — multi-agent delegation, the tier above. - `ziggspay.skill.md` — adding payment tools to your agent.