Credential-Safe Tool Integration: Function Calling Protocols for Platform Teams Building Agentic Systems

// TypeScript — Tool Proxy with scoped credential injection
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';

interface ToolCall {
  name: string;
  args: Record<string, unknown>;
  agentId: string;
  traceId: string;
}

interface ToolResult {
  success: boolean;
  output: unknown;
  credentialId: string; // for audit trail linkage
}

const secrets = new SecretsManagerClient({ region: process.env.AWS_REGION });

async function resolveCredential(toolName: string, agentId: string): Promise<string> {
  // Secret path encodes both tool and agent identity — policy enforced at naming convention
  const secretId = `agents/${agentId}/tools/${toolName}/credential`;
  const { SecretString } = await secrets.send(
    new GetSecretValueCommand({ SecretId: secretId })
  );
  if (!SecretString) throw new Error(`No credential found for ${secretId}`);
  return SecretString;
}

export async function dispatchToolCall(
  call: ToolCall,
  registry: Map<string, (args: Record<string, unknown>, credential: string) => Promise<unknown>>
): Promise<ToolResult> {
  const handler = registry.get(call.name);
  if (!handler) throw new Error(`Unregistered tool: ${call.name}`);

  const credential = await resolveCredential(call.name, call.agentId);
  const credentialId = crypto.randomUUID(); // ephemeral ID for this invocation's audit record

  try {
    const output = await handler(call.args, credential);
    return { success: true, output, credentialId };
  } finally {
    // Credential reference goes out of scope — Vault rotation handles the rest
    // Log credentialId + traceId to your audit sink here
    console.log(JSON.stringify({ event: 'tool_invoked', tool: call.name,
      agentId: call.agentId, traceId: call.traceId, credentialId }));
  }
}

// TypeScript — Immutable tool registry with schema validation
import { z, ZodSchema } from 'zod';

interface ToolRegistryEntry {
  name: string;
  version: string;
  argsSchema: ZodSchema;
  allowedAgentIds: Set<string>; // explicit allowlist, not wildcard
  credentialClass: string; // e.g. 'smtp', 'stripe-readonly', 'github-push'
}

// Registry is built at startup and frozen — no runtime mutation
const TOOL_REGISTRY: ReadonlyMap<string, ToolRegistryEntry> = new Map([
  [
    'send_email',
    {
      name: 'send_email',
      version: '1.2.0',
      argsSchema: z.object({
        to: z.string().email(),
        subject: z.string().max(200),
        body: z.string().max(4000),
      }),
      allowedAgentIds: new Set(['support-agent-v2', 'onboarding-agent-v1']),
      credentialClass: 'smtp',
    },
  ],
]);
Object.freeze(TOOL_REGISTRY);

function validateToolCall(
  toolName: string,
  args: unknown,
  agentId: string
): { valid: true; entry: ToolRegistryEntry } | { valid: false; reason: string } {
  const entry = TOOL_REGISTRY.get(toolName);
  if (!entry) return { valid: false, reason: `Tool '${toolName}' is not registered` };

  const parsed = entry.argsSchema.safeParse(args);
  if (!parsed.success)
    return { valid: false, reason: `Schema violation: ${parsed.error.message}` };

  if (!entry.allowedAgentIds.has(agentId))
    return { valid: false, reason: `Agent '${agentId}' is not authorized for tool '${toolName}'` };

  return { valid: true, entry };
}

// TypeScript — Tool proxy metrics instrumentation using prom-client
import { Counter, Histogram, Registry } from 'prom-client';

const registry = new Registry();

const toolCallTotal = new Counter({
  name: 'agent_tool_call_total',
  help: 'Total tool calls dispatched by agent and result status',
  labelNames: ['tool_name', 'agent_id', 'status'] as const,
  registers: [registry],
});

const toolCallDuration = new Histogram({
  name: 'agent_tool_call_duration_seconds',
  help: 'End-to-end latency per tool call including credential resolution',
  labelNames: ['tool_name'] as const,
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [registry],
});

const credentialErrors = new Counter({
  name: 'agent_tool_credential_errors_total',
  help: 'Credential-related failures disaggregated by error class',
  labelNames: ['tool_name', 'error_class'] as const, // e.g. 'revoked', 'expired', 'unauthorized'
  registers: [registry],
});

export async function instrumentedDispatch(
  toolName: string,
  agentId: string,
  dispatch: () => Promise<unknown>
): Promise<unknown> {
  const end = toolCallDuration.startTimer({ tool_name: toolName });
  try {
    const result = await dispatch();
    toolCallTotal.inc({ tool_name: toolName, agent_id: agentId, status: 'success' });
    return result;
  } catch (err: unknown) {
    const errorClass = classifyToolError(err);
    toolCallTotal.inc({ tool_name: toolName, agent_id: agentId, status: 'error' });
    if (errorClass === 'revoked' || errorClass === 'expired' || errorClass === 'unauthorized') {
      credentialErrors.inc({ tool_name: toolName, error_class: errorClass });
    }
    throw err;
  } finally {
    end();
  }
}

function classifyToolError(err: unknown): string {
  if (err instanceof Error) {
    if (err.message.includes('401') || err.message.includes('revoked')) return 'revoked';
    if (err.message.includes('403')) return 'unauthorized';
    if (err.message.includes('429')) return 'rate_limited';
    if (err.message.includes('timeout')) return 'upstream_timeout';
  }
  return 'unknown';
}

// TypeScript — Local dev proxy using environment-switched secret backend
import type { SecretsBackend } from './types';

class LocalVaultBackend implements SecretsBackend {
  private store: Map<string, string>;

  constructor() {
    // In local dev, secrets come from a local Vault dev instance or .env.secrets
    // Never real credentials — always sandboxed test values
    this.store = new Map([
      ['agents/test-agent/tools/send_email/credential', 'smtp://mock:mock@localhost:1025'],
      ['agents/test-agent/tools/github_pr/credential', 'ghp_MOCK_TOKEN_FOR_LOCAL_DEV'],
    ]);
  }

  async getSecret(path: string): Promise<string> {
    const val = this.store.get(path);
    if (!val) throw new Error(`Local secret not found: ${path}`);
    return val;
  }
}

class AwsSecretsBackend implements SecretsBackend {
  async getSecret(path: string): Promise<string> {
    // Real AWS Secrets Manager call — same interface, different backend
    const { SecretsManagerClient, GetSecretValueCommand } = await import('@aws-sdk/client-secrets-manager');
    const client = new SecretsManagerClient({});
    const { SecretString } = await client.send(new GetSecretValueCommand({ SecretId: path }));
    if (!SecretString) throw new Error(`Secret not found: ${path}`);
    return SecretString;
  }
}

// Same proxy code, different backend — dev/prod parity without credential exposure
export function createSecretsBackend(): SecretsBackend {
  return process.env.NODE_ENV === 'production'
    ? new AwsSecretsBackend()
    : new LocalVaultBackend();
}

// TypeScript — Orchestrator approval gate with PostgreSQL-backed queue
import { Pool } from 'pg';

const db = new Pool({ connectionString: process.env.DATABASE_URL });

interface PendingAction {
  id: string;
  traceId: string;
  agentId: string;
  toolName: string;
  args: Record<string, unknown>;
  status: 'pending' | 'approved' | 'rejected';
  approvedBy?: string;
  justification?: string;
}

export async function requestApproval(
  traceId: string,
  agentId: string,
  toolName: string,
  args: Record<string, unknown>
): Promise<string> {
  const actionId = crypto.randomUUID();
  await db.query(
    `INSERT INTO pending_actions (id, trace_id, agent_id, tool_name, args, status, created_at)
     VALUES ($1, $2, $3, $4, $5, 'pending', NOW())`,
    [actionId, traceId, agentId, toolName, JSON.stringify(args)]
  );
  // Emit to your notification channel (SNS, Slack webhook, etc.)
  await notifyReviewers({ actionId, toolName, agentId, args });
  return actionId;
}

export async function waitForApproval(
  actionId: string,
  timeoutMs = 300_000 // 5 minutes — agent suspends here
): Promise<{ approved: boolean; approvedBy?: string; justification?: string }> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const { rows } = await db.query<PendingAction>(
      `SELECT status, approved_by, justification FROM pending_actions WHERE id = $1`,
      [actionId]
    );
    const action = rows[0];
    if (action?.status === 'approved')
      return { approved: true, approvedBy: action.approvedBy, justification: action.justification };
    if (action?.status === 'rejected')
      return { approved: false, justification: action.justification };
    await new Promise(r => setTimeout(r, 2000)); // poll every 2s
  }
  throw new Error(`Approval timeout for action ${actionId}`);
}

async function notifyReviewers(payload: unknown): Promise<void> {
  // Wire to SNS, Slack, PagerDuty — implementation left to your notification layer
  console.log('[approval-gate] Notifying reviewers:', JSON.stringify(payload));
}