@certnode/agent-sdk

Accountability infrastructure for AI agents. Create cryptographic proof of every action your AI agent takes, with human authorization chains.

Why Agent Accountability?

As AI agents take more autonomous actions, there's growing need to:

• Track what agents do - Immutable audit log of every action
• Prove authorization - Human-granted permissions with scope limits
• Detect violations - Flag actions outside authorized scope
• Enable compliance - RFC 3161 timestamps for regulatory requirements

Installation

npm install @certnode/agent-sdk

Quick Start

import { AgentClient } from '@certnode/agent-sdk'

// Initialize the client
const agent = new AgentClient({
  apiKey: process.env.CERTNODE_API_KEY,
  agentType: 'claude-agent',
  agentName: 'Customer Service Bot',
  agentVersion: '1.0.0',
  capabilities: ['read_tickets', 'respond_tickets', 'escalate_tickets'],
})

// Create an authorization from a human supervisor
const auth = await agent.createAuthorization({
  grantedByUserId: 'supervisor_123',
  grantedByName: 'Sarah Chen',
  grantedByEmail: '[email protected]',
  scope: ['read_tickets', 'respond_tickets'],
  prohibitedActions: ['delete_tickets', 'issue_refunds'],
  expiresAt: new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString(), // 8 hours
  reason: 'Weekend shift coverage',
})

// Log an action
const action = await agent.logAction({
  authorizationId: auth.id,
  actionType: 'respond_tickets',
  actionDescription: 'Sent response to ticket #12345',
  actionDetails: {
    ticketId: '12345',
    message: 'Thank you for contacting us...',
  },
})

console.log(`Action logged: ${action.action.id}`)
console.log(`Within scope: ${action.action.withinScope}`)
console.log(`Proof URL: https://certnode.io/verify/${action.action.id}`)

Core Concepts

Authorization Chain

Every agent action must be authorized by a human. Authorizations include:

• Scope: What actions the agent can take
• Constraints: Limits on how actions can be performed
• Prohibited actions: Explicitly forbidden operations
• Time bounds: When the authorization expires

const auth = await agent.createAuthorization({
  grantedByUserId: 'user_123',
  grantedByName: 'John Doe',
  scope: ['analyze_data', 'generate_report'],
  constraints: {
    maxRecordsPerQuery: 1000,
    allowedDatabases: ['analytics', 'reporting'],
  },
  prohibitedActions: ['delete_data', 'export_pii'],
  expiresAt: '2026-01-31T23:59:59Z',
})

Action Logging

Every action is logged with cryptographic proof:

const result = await agent.logAction({
  authorizationId: auth.id,
  actionType: 'analyze_data',
  actionDescription: 'Analyzed Q4 sales data',
  actionDetails: {
    query: 'SELECT region, SUM(revenue) FROM sales GROUP BY region',
    rowCount: 45,
  },
  parentActionId: previousAction.id, // Optional: link to parent action
  sessionId: 'session_abc123', // Optional: group related actions
})

// Check if action was within scope
if (!result.action.withinScope) {
  console.warn('Scope violation:', result.violations)
}

Proof Verification

Every action receives:

• SHA-256 content hash - Tamper-evident fingerprint
• JWS signature - ES256 cryptographic signature
• RFC 3161 timestamp - Legally compliant timestamp

// Verify an action
const verification = await agent.verifyAction(actionId)
console.log(verification.valid) // true
console.log(verification.contentHash) // sha256:abc123...
console.log(verification.rfc3161Timestamp) // 2026-01-05T12:00:00Z

API Reference

AgentClient

new AgentClient(options: AgentClientOptions)

Options: | Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your CertNode API key | | agentType | string | Yes | Agent type identifier | | agentName | string | Yes | Human-readable agent name | | agentVersion | string | No | Semantic version | | description | string | No | Agent description | | capabilities | string[] | No | List of capabilities | | baseUrl | string | No | API base URL (default: https://api.certnode.io) |

createAuthorization()

agent.createAuthorization(params: CreateAuthorizationParams): Promise<Authorization>

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | grantedByUserId | string | Yes | User ID of grantor | | grantedByName | string | Yes | Name of grantor | | grantedByEmail | string | No | Email of grantor | | grantedByTitle | string | No | Job title of grantor | | scope | string[] | Yes | Allowed action types | | constraints | object | No | Action constraints | | prohibitedActions | string[] | No | Explicitly forbidden actions | | validFrom | string | No | ISO timestamp (default: now) | | expiresAt | string | No | ISO timestamp | | reason | string | No | Reason for authorization |

logAction()

agent.logAction(params: LogActionParams): Promise<ActionResult>

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | authorizationId | string | Yes | Authorization ID | | actionType | string | Yes | Type of action | | actionDescription | string | Yes | Human-readable description | | actionDetails | object | No | Structured action data | | parentActionId | string | No | Parent action for chaining | | sessionId | string | No | Session identifier |

listActions()

agent.listActions(params: ListActionsParams): Promise<ActionList>

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | authorizationId | string | Filter by authorization | | sessionId | string | Filter by session | | actionType | string | Filter by action type | | withinScope | boolean | Filter by scope status | | limit | number | Results per page (default: 50) | | offset | number | Pagination offset |

revokeAuthorization()

agent.revokeAuthorization(authorizationId: string, reason?: string): Promise<void>

Integration Examples

With Claude (Anthropic)

import { AgentClient } from '@certnode/agent-sdk'
import Anthropic from '@anthropic-ai/sdk'

const agent = new AgentClient({
  apiKey: process.env.CERTNODE_API_KEY,
  agentType: 'claude-agent',
  agentName: 'Content Moderator',
})

const anthropic = new Anthropic()

async function moderateContent(authId: string, content: string) {
  // Log the moderation action
  const action = await agent.logAction({
    authorizationId: authId,
    actionType: 'moderate_content',
    actionDescription: 'Analyzing content for policy violations',
    actionDetails: { contentLength: content.length },
  })

  // Call Claude
  const result = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    messages: [{ role: 'user', content: `Moderate this: ${content}` }],
  })

  return { action, result }
}

With OpenAI

import { AgentClient } from '@certnode/agent-sdk'
import OpenAI from 'openai'

const agent = new AgentClient({
  apiKey: process.env.CERTNODE_API_KEY,
  agentType: 'openai-agent',
  agentName: 'Data Analyst',
})

const openai = new OpenAI()

async function analyzeData(authId: string, data: object[]) {
  const action = await agent.logAction({
    authorizationId: authId,
    actionType: 'analyze_data',
    actionDescription: 'Running data analysis',
    actionDetails: { recordCount: data.length },
  })

  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'Analyze the data and provide insights.' },
      { role: 'user', content: JSON.stringify(data) },
    ],
  })

  return { action, analysis: completion.choices[0].message.content }
}

Dashboard

View all agent activity at certnode.io/dashboard/agents:

• Real-time action feed
• Authorization management
• Scope violation alerts
• Audit log export

Error Handling

import { AgentClient, AgentError, AuthorizationExpiredError } from '@certnode/agent-sdk'

try {
  await agent.logAction({ ... })
} catch (error) {
  if (error instanceof AuthorizationExpiredError) {
    // Request new authorization
  } else if (error instanceof AgentError) {
    console.error('Agent error:', error.code, error.message)
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  AgentClientOptions,
  Authorization,
  CreateAuthorizationParams,
  LogActionParams,
  ActionResult,
  AgentAction,
} from '@certnode/agent-sdk'

License

MIT

Links

• Documentation
• API Reference
• Dashboard
• GitHub