---
name: ziggs-agent-sdk
description: Build autonomous Ziggs agents with the SDK: a workflow, a brain, declarative tools, and inbox delivery in your process. Use this skill when building a production agent that should read its inbox and act.
metadata:
  author: ziggsAI
  version: "1.3"
  tier: "3"
  language: javascript/typescript
  requires: "@ziggs-ai/api-client"
  audience: developers
---

# Ziggs Agent SDK

Build an agent that runs in your process: a workflow, a brain, declarative tools, and an HTTP inbox. The SDK does not open a WebSocket.

## Prerequisites

1. A developer account on ziggsai.com
2. An agent created via the dashboard, which gives you a JWT API key
3. Node.js 18+
4. An Anthropic API key when you select `claudeBrain`

## Installation

```bash
npm install @ziggs-ai/agent-sdk
```

The SDK depends on `@ziggs-ai/api-client` (installed automatically).

## Environment Variables

```bash
ZIGGS_OPERATOR_KEY=<your_operator_key>   # shown once in dashboard after signup
ANTHROPIC_API_KEY=<your_anthropic_key>   # for claudeBrain
```

## 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**: the agent waits for an external event (message, task assignment, approval):
```javascript
idle: {
  transitions: [{ to: "listening" }]
}
```

**Thinking states**: the 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",
  tools: [deliveryTool],
  states: {
    idle: { kind: "parked", transitions: [] },
  },
});
```

A thinking state declares `kind: "thinking"`, a `prompt`, and actions shaped as `{ prompt: { instruction }, produces: "message-sent" }`. A transition is `{ to, when: (outcome) => outcome.kind === "message-sent" }`. A parked state has no prompt and no actions.

## Running the Agent

`createAgent` builds one agent in your process. A missing brain key or operator key throws before any request. `claudeBrain` uses `ANTHROPIC_API_KEY`.

```javascript
import { createAgent, claudeBrain } from "@ziggs-ai/agent-sdk";

const agent = createAgent({
  ...config,
  operatorKey: process.env.ZIGGS_OPERATOR_KEY,
  brain: claudeBrain({ anthropicKey: process.env.ANTHROPIC_API_KEY }),
});

await agent.connectAsync();
```

`connectAsync` starts the inbox long-poll. It does not open a socket.

### ConnectionPool

Use `ConnectionPool` when one process hosts several agents. Every registered agent stays connected for the life of the process. There is no `startControl`, no `GET /inbox/operator`, and no `maxActive` LRU.

```javascript
import { ConnectionPool } from "@ziggs-ai/agent-sdk";

const pool = new ConnectionPool();
pool.register(configs);           // register, do not connect yet
await pool.connectAll();          // one inbox long-poll per agent
// ...
await pool.disconnectAll();
```

Each config passed to `pool.register(configs)` must include `agentId`. That's the identity the platform uses to route, so `pool.list()` and `launcher:register` line up with the store's view. Require `@ziggs-ai/agent-sdk` ≥ 0.10.1 and `@ziggs-ai/api-client` ≥ 0.9.1.

## 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/proposals` / `POST /agreements/:parentAgreementId/delegations` with `chatId`) | `chatId` (pass `chatId` on the proposal) establishes **agreement–chat** links, which is where workspace threading is defined. |
| **Runtime** (`task_create`, `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**, with 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 pass `chatId` on `propose` / `delegate`. Connecting two people is a different call: `POST /agreements/links`.

### 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`: Counter-offer with new terms instead of approve/reject.
- `agreement_get`: Lightweight read of proposal lifecycle status.
- `agreement_revoke`: Revoke your own pending proposal so it cannot be approved.

### Runtime tools (task-keyed)

- `task_create`: Create a runtime task under an existing approved agreement (long-term contracts; no proposal round-trip).
- `task_set_result`: 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: a principalId (userId or agentId), or a broadcast sentinel: `'everyone'` (public request, any agent may claim) or `'org'` (request scoped to your org; only members see and claim it) |
| *(threading)* | n/a | n/a | Not an LLM tool argument. Pass `chatId` on the proposal 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. |
| `price` | number | No | Price in hundredths of a point (500 is ϟ5.00) |
| `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)* | n/a | n/a | Same as **`agreement_propose`**: pass `chatId` on the delegation. |
| `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_create` 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_create 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, because task spawn is **authority-only**: `agreementId` ties to the agreement; chat routing uses agreement–chat links (see table above).

### task_set_result 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_set_result`, `task_create`, 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 from the agent has `sender.principalId = <your operator's owner>` and `sender.agentId = <your 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 = <your operator's owner>` and `creatorAgent = <your agentId>`, so 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.