DocumentationAgent Action Firewall
GitHub

Submit Your First Action

Learn how to submit actions through the firewall and handle different response scenarios.

Basic Action Submission

Submit an HTTP Request

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

const client = new AgentFirewallClient({
  baseUrl: process.env.AGENT_FIREWALL_BASE_URL!,
  apiKey: process.env.AGENT_FIREWALL_API_KEY!,
  agentId: 'my-agent',
});

// Submit an HTTP action for policy evaluation
const response = await client.submitAction({
  tool: 'http_proxy',
  operation: 'POST',
  params: {
    url: 'https://api.example.com/data',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: {
      key: 'value',
    },
  },
});

console.log('Action ID:', response.id);
console.log('Status:', response.status);

Handling Response Statuses

Allowed Actions

TypeScript
if (response.status === 'allowed') {
  // Action approved - proceed with execution
  console.log('Action allowed, executing...');

  // The firewall may have already executed the action
  if (response.execution?.result) {
    console.log('Result:', response.execution.result);
  }
}

Pending Approval

TypeScript
if (response.status === 'pending_approval') {
  console.log('Waiting for human approval...');

  // Option 1: Poll for approval
  const approved = await client.waitForApproval(response.id, {
    timeout: 300000, // 5 minutes
    pollInterval: 5000, // Check every 5 seconds
  });

  if (approved.status === 'allowed') {
    console.log('Approved! Proceeding...');
  } else {
    console.log('Denied or timed out');
  }
}

Denied Actions

TypeScript
if (response.status === 'denied') {
  console.log('Action denied');
  console.log('Reason:', response.decision?.reason);

  // Handle denial gracefully
  // - Log the denial for debugging
  // - Notify the user if applicable
  // - Try an alternative approach
}

Complete Example

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

async function executeSecureAction() {
  const client = new AgentFirewallClient({
    baseUrl: process.env.AGENT_FIREWALL_BASE_URL!,
    apiKey: process.env.AGENT_FIREWALL_API_KEY!,
    agentId: 'customer-service-agent',
  });

  try {
    const response = await client.submitAction({
      tool: 'http_proxy',
      operation: 'POST',
      params: {
        url: 'https://api.company.com/customers/update',
        method: 'POST',
        body: { customerId: '123', status: 'verified' },
      },
    });

    switch (response.status) {
      case 'allowed':
        return { success: true, result: response.execution?.result };

      case 'pending_approval':
        const final = await client.waitForApproval(response.id);
        if (final.status === 'allowed') {
          return { success: true, result: final.execution?.result };
        }
        return { success: false, reason: 'Approval denied or timed out' };

      case 'denied':
        return { success: false, reason: response.decision?.reason };

      default:
        return { success: false, reason: 'Unknown status' };
    }
  } catch (error) {
    console.error('Firewall error:', error);
    return { success: false, reason: 'Firewall communication failed' };
  }
}

// Use in your agent
const result = await executeSecureAction();
console.log(result);

Action Types

HTTP Proxy

Route HTTP requests through the firewall for policy evaluation.

TypeScript
{
  tool: 'http_proxy',
  operation: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
  params: {
    url: string,
    method: string,
    headers?: Record<string, string>,
    body?: unknown,
  }
}

Database Operations

Evaluate database queries before execution.

TypeScript
{
  tool: 'database',
  operation: 'query' | 'insert' | 'update' | 'delete',
  params: {
    table: string,
    query?: string,
    data?: Record<string, unknown>,
  }
}

Next Steps