DocumentationAgent Action Firewall
GitHub

TypeScript SDK Reference

Complete API reference for the Agent Action Firewall TypeScript SDK.

Installation

Bash
npm install @agent-action-firewall/sdk

AgentFirewallClient

The main client class for interacting with the Agent Action Firewall API.

Constructor

TypeScript
import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const client = new AgentFirewallClient({
  baseUrl: string;       // API base URL
  apiKey: string;        // Your agent API key
  agentId: string;       // Unique identifier for this agent
  timeout?: number;      // Request timeout in ms (default: 30000)
  retries?: number;      // Number of retry attempts (default: 3)
});

Methods

submitAction()

Submit an action for policy evaluation and optional execution.

TypeScript
const response = await client.submitAction({
  tool: string;           // Tool/connector name (e.g., 'http_proxy', 'jira')
  operation: string;      // Operation type (e.g., 'GET', 'POST', 'create_issue')
  params: object;         // Tool-specific parameters
  context?: {
    user_id?: string;     // End user identifier
    session_id?: string;  // Session/conversation ID
    metadata?: object;    // Additional context
  };
  idempotency_key?: string;  // Prevent duplicate submissions
});

// Response
interface ActionResponse {
  id: string;                          // Action request ID
  status: 'allowed' | 'denied' | 'pending_approval' | 'queued';
  decision?: {
    action: 'allow' | 'deny' | 'require_approval';
    reason?: string;
    risk_level?: 'low' | 'medium' | 'high' | 'critical';
    policy_id?: string;
  };
  result?: object;                     // Execution result (if allowed)
  approval_url?: string;               // URL to approve (if pending)
}

getAction()

Get the current status and details of an action request.

TypeScript
const action = await client.getAction(actionId: string);

// Returns ActionResponse with current status

waitForApproval()

Poll for approval status until resolved or timeout.

TypeScript
const result = await client.waitForApproval(actionId: string, {
  timeout?: number;       // Max wait time in ms (default: 300000 / 5 min)
  pollInterval?: number;  // Poll interval in ms (default: 2000)
});

// Returns final ActionResponse with 'approved' | 'rejected' | 'expired' status

cancelAction()

Cancel a pending action request.

TypeScript
await client.cancelAction(actionId: string);

Error Handling

TypeScript
import {
  AgentFirewallError,
  RateLimitError,
  AuthenticationError,
  PolicyDeniedError
} from '@agent-action-firewall/sdk';

try {
  const response = await client.submitAction({...});
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    await sleep(error.retryAfter);
  } else if (error instanceof AuthenticationError) {
    // Check API key configuration
  } else if (error instanceof PolicyDeniedError) {
    // Action was denied by policy
    console.log('Denied:', error.reason);
  }
}

Types

ActionRequest

TypeScript
interface ActionRequest {
  tool: string;
  operation: string;
  params: Record<string, unknown>;
  context?: ActionContext;
  idempotency_key?: string;
}

interface ActionContext {
  user_id?: string;
  session_id?: string;
  metadata?: Record<string, unknown>;
}

ActionStatus

TypeScript
type ActionStatus =
  | 'pending_decision'   // Awaiting policy evaluation
  | 'allowed'            // Approved by policy, executing
  | 'denied'             // Blocked by policy
  | 'pending_approval'   // Awaiting human approval
  | 'approved'           // Human approved
  | 'rejected'           // Human rejected
  | 'expired'            // Approval timeout
  | 'queued'             // Queued for execution
  | 'running'            // Currently executing
  | 'succeeded'          // Completed successfully
  | 'failed';            // Execution failed

Examples

HTTP Proxy Action

TypeScript
const response = await client.submitAction({
  tool: 'http_proxy',
  operation: 'POST',
  params: {
    url: 'https://api.example.com/users',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: { name: 'John Doe', email: 'john@example.com' },
  },
});

Jira Action

TypeScript
const response = await client.submitAction({
  tool: 'jira',
  operation: 'create_issue',
  params: {
    project: 'PROJ',
    issueType: 'Task',
    summary: 'New task from AI agent',
    description: 'Created automatically by AI assistant',
  },
});

With Idempotency

TypeScript
// Safe to retry - won't create duplicate actions
const response = await client.submitAction({
  tool: 'http_proxy',
  operation: 'POST',
  params: { url: 'https://api.example.com/orders', body: order },
  idempotency_key: `order-${orderId}`,
});

Next Steps