Skip to main content

Instrument Your First Agent

This guide shows how to add Sequenceware governance to an existing agent. Your agent code stays the same — you just wrap tool calls with tracking.

The pattern​

Every agent follows the same lifecycle:

1. Start a run          →  client.startRun()
2. Track each tool call →  client.trackToolCall()
3. Report results       →  client.completeToolCall()
4. End the run          →  client.completeRun()

Sequenceware evaluates policies at step 2. If a policy matches, the tool call is either blocked, allowed with a warning, or paused for human approval.

TypeScript example​

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

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

async function myAgentWorkflow() {
  // 1. Start a run (with optional agent context for observability)
  const runId = await client.startRun(
    undefined,
    { task: 'Review and fix authentication module' },
    undefined,
    {
      goal: 'Fix the session expiry bug',
      reasoning: 'User reported that sessions expire prematurely after re-login',
    },
  );

  try {
    // 2. Track a read operation
    const readTcId = await client.trackToolCall(runId, 'read_file', {
      path: 'src/auth/session.ts',
    });
    const fileContent = await readFile('src/auth/session.ts');
    await client.completeToolCall(runId, readTcId, { lines: fileContent.length });

    // 3. Track a write operation
    const writeTcId = await client.trackToolCall(runId, 'write_file', {
      path: 'src/auth/session.ts',
      changes: 'Fix token expiry logic',
    });
    await writeFile('src/auth/session.ts', updatedContent);
    await client.completeToolCall(runId, writeTcId, { success: true });

    // 4. Track a potentially risky operation
    const deployTcId = await client.trackToolCall(runId, 'deploy', {
      environment: 'production',
      service: 'auth-api',
    });

    // Check the policy decision
    const run = await client.getRun(runId);
    const tc = run.toolCalls?.find((t: any) => t.toolCallId === deployTcId);

    if (tc?.status === 'blocked') {
      console.log('Deploy blocked by policy:', tc.blockedReason);
    } else if (tc?.status === 'awaiting_approval') {
      console.log('Deploy requires human approval. Check the dashboard.');
    } else {
      await deployToProduction();
      await client.completeToolCall(runId, deployTcId, { deployed: true });
    }

    // 5. Complete the run
    await client.completeRun(runId);
  } catch (error) {
    await client.failRun(runId, { error: String(error) });
    throw error;
  }
}

Python example​

from sequenceware import SequencewareClient

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

# Context manager handles run lifecycle automatically
with client.run(metadata={"task": "Review auth module"}) as run:

    # Steps group related tool calls
    with run.step({"phase": "analysis"}):
        tc_id = run.track_tool("read_file", {"path": "src/auth/session.ts"})
        content = read_file("src/auth/session.ts")
        run.complete_tool(tc_id, {"lines": len(content)})

    with run.step({"phase": "fix"}):
        tc_id = run.track_tool("write_file", {
            "path": "src/auth/session.ts",
            "changes": "Fix token expiry",
        })
        write_file("src/auth/session.ts", updated)
        run.complete_tool(tc_id, {"success": True})

# Run is auto-completed on exit (or marked failed if an exception occurs)

What happens in the dashboard​

After running the agent, you'll see:

Run: my-agent                                    Status: completed
├── Step: analysis
│   └── read_file("src/auth/session.ts")         ALLOWED
├── Step: fix
│   └── write_file("src/auth/session.ts")        ALLOWED
└── deploy(env=production)                        REQUIRES APPROVAL
    └── Policy: approve-prod-deploy
    └── Waiting for reviewer...

Each tool call shows:

  • Input payload — what the agent tried to do
  • Output payload — what happened
  • Policy matches — which policies evaluated and their decisions
  • Audit trail — timestamps, actors, and decisions

Next steps​