Skip to main content

SDK Overview

Sequenceware provides SDKs for TypeScript and Python. Use them to track run lifecycle and enforce governance decisions on every tool call.

Core concepts​

Runs​

A run represents a single agent session or task execution.

const runId = await client.startRun(
  undefined,
  { task: 'Fix auth bug' },
  'Fix the session expiry bug reported in JIRA-1234',
);
// ... agent work ...
await client.completeRun(runId);

Steps​

Steps are optional groupings inside a run.

with run.step({"phase": "analysis"}):
    run.track_tool("read_file", {"path": "auth.ts"})

with run.step({"phase": "fix"}):
    run.track_tool("write_file", {"path": "auth.ts", "content": "..."})

Tool calls​

A tool call is any action your agent takes. Policy evaluation happens here.

const tcId = await client.trackToolCall(
  runId,
  'deploy',
  { environment: 'production' },
  undefined,
  undefined,
  'Deploying hotfix to resolve customer-facing outage',
);

When you track a tool call, Sequenceware:

  1. Persists the event
  2. Evaluates all enabled policies
  3. Returns the tool call ID
  4. Sets status: allowed, blocked, or awaiting_approval

Agent context​

Attach AgentContext for better approval and audit visibility:

import { AgentContext } from '@sequenceware/sdk';

const context: AgentContext = {
  goal: 'Fix the session expiry bug reported in JIRA-1234',
  reasoning: 'Session tokens are not being refreshed on re-authentication',
  conversationId: 'conv_abc123',
};

const runId = await client.startRun(undefined, { task: 'Fix auth bug' }, undefined, context);

await client.trackToolCall(
  runId,
  'deploy',
  { environment: 'production' },
  undefined,
  'deploy',
  'Deploying hotfix to resolve customer-facing outage',
  { goal: context.goal, reasoning: 'Fix verified in staging, deploying to prod' },
);

See AgentContext.

Action hints​

Use action hints to improve policy matching:

await client.trackToolCall(
  runId,
  'git_push',
  { branch: 'main' },
  undefined,
  'pr_merge',
  'Merging because tests pass and reviewer approved',
);

Coding-agent quickstart examples​

TypeScript: govern a coding workflow​

import { SequencewareClient } from '@sequenceware/sdk';

const client = new SequencewareClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.SEQUENCEWARE_API_KEY,
  agentId: 'claude-code',
});

const runId = await client.startRun(undefined, {
  task: 'Prepare release branch',
  source: 'coding-agent',
});

const toolCallId = await client.trackToolCall(
  runId,
  'Bash',
  { command: 'git push --force origin release/v1.8.0' },
  undefined,
  'config_change',
  'Sync release branch before deployment',
);

const run = await client.getRun(runId);
const call = run.toolCalls?.find((entry: any) => entry.toolCallId === toolCallId);
if (call?.status === 'blocked') {
  throw new Error(`Blocked by policy: ${call.blockedReason ?? 'no reason provided'}`);
}

await client.completeToolCall(runId, toolCallId, { executed: true });
await client.completeRun(runId);

Python: govern file edits​

from sequenceware import SequencewareClient

client = SequencewareClient(
    base_url="http://localhost:3000",
    api_key="acl_replace_with_your_key",
    agent_id="custom-coding-agent",
)

with client.run(metadata={"task": "update ci pipeline", "source": "coding-agent"}) as run:
    run.track_tool(
        "Edit",
        {
            "file_path": ".github/workflows/release.yml",
            "old_string": "npm test",
            "new_string": "npm run test:e2e",
        },
    )

TypeScript SDK​

npm install @sequenceware/sdk
import { SequencewareClient } from '@sequenceware/sdk';

const client = new SequencewareClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'acl_...',
  agentId: 'my-agent',
});

Python SDK​

pip install sequenceware
from sequenceware import SequencewareClient

client = SequencewareClient(
    base_url="http://localhost:3000",
    api_key="acl_...",
    agent_id="my-agent",
)

Context managers​

# Run is auto-completed on exit, or auto-failed on exception
with client.run(metadata={"task": "deploy"}) as run:
    with run.step({"phase": "build"}):
        run.track_tool("npm_build", {"project": "api"})

Integration guides​

Error handling​

import {
  AuthenticationError,
  RateLimitError,
  ServerError,
} from '@sequenceware/sdk';

try {
  await client.trackToolCall(runId, 'deploy', { env: 'prod' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof RateLimitError) {
    // Too many requests
  } else if (error instanceof ServerError) {
    // Sequenceware server error
  }
}

Retry behavior​

Both SDKs include automatic retries with exponential backoff:

  • Default retries: 3
  • Default delay: 1000ms (doubles each retry)
  • Retried errors: network failures, 5xx, and rate limits

Configure via constructor:

const client = new SequencewareClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'acl_...',
  agentId: 'my-agent',
  apiVersion: 'v1',   // default; all requests prefixed with /v1/
  maxRetries: 5,
  retryDelay: 2000,
  timeout: 15000,
});

API versioning​

The SDK uses URI-based API versioning. All requests are automatically prefixed with /v1/ (or the value of apiVersion). The SDK also sends an X-SDK-Version header with every request so the server can track client compatibility.

// Default: requests go to /v1/events, /v1/runs, etc.
const client = new SequencewareClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'acl_...',
  agentId: 'my-agent',
});