Agent Action Firewall TypeScript SDK

Official TypeScript SDK for the Agent Action Firewall - a security layer for AI agents.

Installation

``bash
npm install @agent-action-firewall/sdk


or

pnpm add @agent-action-firewall/sdk

or

yarn add @agent-action-firewall/sdk
`

Quick Start

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

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

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

console.log('Action status:', response.status);
`

Usage

$3

`typescript
const response = await client.submitAction({
tool: 'http_proxy',
operation: 'POST',
params: {
url: 'https://api.example.com/data',
body: { key: 'value' },
},
// Optional: prevent duplicate submissions
idempotencyKey: 'unique-request-id',
});

switch (response.status) {
case 'allowed':
// Action is allowed, execute it
console.log('Action allowed');
break;
case 'denied':
// Action was denied by policy
console.log('Denied:', response.decision?.reason);
break;
case 'pending_approval':
// Requires human approval
console.log('Waiting for approval:', response.approvalId);
break;
}
`

$3

`typescript
const detail = await client.getAction(actionId);
console.log('Status:', detail.status);
console.log('Decision:', detail.decision);
console.log('Approval:', detail.approval);
`

$3

`typescript
// Wait up to 5 minutes for approval
const finalStatus = await client.waitForApproval(actionId, {
timeout: 300000,
interval: 2000, // Poll every 2 seconds
onStatusChange: (status) => {
console.log('Status update:', status.status);
},
});

console.log('Final status:', finalStatus.status);
`

$3

Convenience method that submits an action and waits for completion:

`typescript
const result = await client.submitAndWait({
tool: 'jira',
operation: 'create_ticket',
params: {
project: 'PROJ',
summary: 'New ticket',
description: 'Created by AI agent',
},
});

if (result.status === 'succeeded') {
console.log('Ticket created:', result.execution?.result);
}
`

Configuration Options

`typescript
const client = new AgentFirewallClient({
// Required
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: 'your-api-key',
agentId: 'your-agent-id',

// Optional
timeout: 30000, // Request timeout in ms (default: 30000)
debug: false, // Enable debug logging
});
`

Error Handling

`typescript
import { AgentFirewallError } from '@agent-action-firewall/sdk';

try {
await client.submitAction({ ... });
} catch (error) {
if (error instanceof AgentFirewallError) {
console.error('Code:', error.code);
console.error('Message:', error.message);
console.error('Status:', error.statusCode);
console.error('Details:', error.details);
}
}
`

$3

- CONFIG_ERROR - Invalid configuration
- NETWORK_ERROR - Network connectivity issue
- TIMEOUT_ERROR - Request or polling timeout
- API_ERROR - API returned an error response

Types

The SDK exports TypeScript types for all request and response objects:

`typescript
import type {
AgentFirewallConfig,
ActionRequest,
ActionResponse,
ActionDetail,
ActionDecision,
ApprovalSummary,
ExecutionSummary,
PollOptions,
} from '@agent-action-firewall/sdk';
`

Integration Examples

$3

Wrap OpenAI function calls with firewall governance:

`typescript
import OpenAI from 'openai';
import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const openai = new OpenAI();
const firewall = new AgentFirewallClient({
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: process.env.AGENT_FIREWALL_API_KEY!,
agentId: 'openai-assistant',
});

// Define a governed function
async function executeFunction(name: string, args: Record) {
// Check with firewall before executing
const response = await firewall.submitAndWait({
tool: name,
operation: 'execute',
params: args,
});

if (response.status === 'denied') {
throw new Error(Action denied: ${response.decision?.reason});
}

// Execute the actual function
return await actualFunctionExecution(name, args);
}

// Use with OpenAI
const completion = await openai.chat.completions.create({
model: 'gpt-4',
messages: [{ role: 'user', content: 'Create a Jira ticket for the bug' }],
tools: [
{
type: 'function',
function: {
name: 'create_jira_ticket',
parameters: { / ... / },
},
},
],
});

// When OpenAI wants to call a function
for (const call of completion.choices[0].message.tool_calls || []) {
const result = await executeFunction(
call.function.name,
JSON.parse(call.function.arguments)
);
}
`

$3

Integrate with Claude's tool use capabilities:

`typescript
import Anthropic from '@anthropic-ai/sdk';
import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const anthropic = new Anthropic();
const firewall = new AgentFirewallClient({
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: process.env.AGENT_FIREWALL_API_KEY!,
agentId: 'claude-assistant',
});

async function handleToolUse(toolName: string, toolInput: Record) {
// Submit to firewall
const response = await firewall.submitAndWait({
tool: toolName,
operation: 'execute',
params: toolInput,
metadata: {
source: 'claude',
model: 'claude-3-opus',
},
});

if (response.status !== 'succeeded') {
return { error: Action ${response.status}: ${response.decision?.reason} };
}

return response.execution?.result;
}

const message = await anthropic.messages.create({
model: 'claude-3-opus-20240229',
max_tokens: 1024,
tools: [
{
name: 'send_email',
description: 'Send an email to a recipient',
input_schema: {
type: 'object',
properties: {
to: { type: 'string' },
subject: { type: 'string' },
body: { type: 'string' },
},
required: ['to', 'subject', 'body'],
},
},
],
messages: [{ role: 'user', content: 'Send an email to team@example.com' }],
});

// Process tool use blocks
for (const block of message.content) {
if (block.type === 'tool_use') {
const result = await handleToolUse(block.name, block.input);
// Continue conversation with result...
}
}
`

$3

Use with the Vercel AI SDK for streaming responses:

`typescript
import { openai } from '@ai-sdk/openai';
import { streamText, tool } from 'ai';
import { z } from 'zod';
import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const firewall = new AgentFirewallClient({
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: process.env.AGENT_FIREWALL_API_KEY!,
agentId: 'vercel-ai-agent',
});

const result = await streamText({
model: openai('gpt-4-turbo'),
tools: {
createTicket: tool({
description: 'Create a support ticket',
parameters: z.object({
title: z.string(),
description: z.string(),
priority: z.enum(['low', 'medium', 'high']),
}),
execute: async ({ title, description, priority }) => {
// Firewall check
const response = await firewall.submitAndWait({
tool: 'ticketing',
operation: 'create',
params: { title, description, priority },
});

if (response.status === 'denied') {
return { error: response.decision?.reason };
}

return { ticketId: response.execution?.result?.id };
},
}),
},
messages: [{ role: 'user', content: 'Create a high priority ticket for the outage' }],
});
`

$3

Wrap LangChain tools with firewall governance:

`typescript
import { ChatOpenAI } from '@langchain/openai';
import { DynamicStructuredTool } from '@langchain/core/tools';
import { AgentExecutor, createOpenAIToolsAgent } from 'langchain/agents';
import { AgentFirewallClient } from '@agent-action-firewall/sdk';
import { z } from 'zod';

const firewall = new AgentFirewallClient({
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: process.env.AGENT_FIREWALL_API_KEY!,
agentId: 'langchain-agent',
});

// Create a governed tool
const governedSearchTool = new DynamicStructuredTool({
name: 'web_search',
description: 'Search the web for information',
schema: z.object({
query: z.string().describe('The search query'),
}),
func: async ({ query }) => {
// Check with firewall first
const response = await firewall.submitAndWait({
tool: 'web_search',
operation: 'search',
params: { query },
});

if (response.status === 'denied') {
throw new Error(Search denied: ${response.decision?.reason});
}

// Execute actual search
return await performWebSearch(query);
},
});

const llm = new ChatOpenAI({ model: 'gpt-4' });
const agent = await createOpenAIToolsAgent({
llm,
tools: [governedSearchTool],
prompt: / your prompt /,
});
`

$3

Create middleware for API routes that require firewall approval:

`typescript
import express from 'express';
import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const app = express();
const firewall = new AgentFirewallClient({
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: process.env.AGENT_FIREWALL_API_KEY!,
agentId: 'api-gateway',
});

// Middleware to check firewall for all agent actions
const firewallMiddleware = (toolName: string) => {
return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
try {
const response = await firewall.submitAction({
tool: toolName,
operation: req.method,
params: {
path: req.path,
body: req.body,
query: req.query,
},
metadata: {
ip: req.ip,
userAgent: req.get('user-agent'),
},
});

if (response.status === 'denied') {
return res.status(403).json({
error: 'Action denied by policy',
reason: response.decision?.reason,
riskLevel: response.decision?.riskLevel,
});
}

if (response.status === 'pending_approval') {
return res.status(202).json({
message: 'Action requires approval',
approvalId: response.approvalId,
actionId: response.id,
});
}

// Attach action info to request for logging
req.firewallAction = response;
next();
} catch (error) {
next(error);
}
};
};

// Use on routes
app.post('/api/agents/:agentId/execute',
firewallMiddleware('agent_execution'),
async (req, res) => {
// Action was approved, proceed with execution
const result = await executeAgentAction(req.body);
res.json(result);
}
);
`

$3

Protect Next.js API routes with firewall checks:

`typescript
// app/api/agent/action/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const firewall = new AgentFirewallClient({
baseUrl: 'https://api.agentactionfirewall.com',
apiKey: process.env.AGENT_FIREWALL_API_KEY!,
agentId: 'nextjs-agent',
});

export async function POST(request: NextRequest) {
const body = await request.json();

// Submit to firewall
const response = await firewall.submitAndWait({
tool: body.tool,
operation: body.operation,
params: body.params,
});

if (response.status === 'denied') {
return NextResponse.json(
{ error: 'Denied', reason: response.decision?.reason },
{ status: 403 }
);
}

if (response.status === 'succeeded') {
return NextResponse.json({
success: true,
result: response.execution?.result,
});
}

return NextResponse.json(
{ error: 'Action failed', status: response.status },
{ status: 400 }
);
}
``

License

MIT