Adaptive Agentic Integration: How to Wire Agents Into Microservices Without Painting Yourself Into a Corner

// TypeScript: Dynamic tool binding from live OpenAPI spec
import { zodToJsonSchema } from 'zod-to-json-schema';
import { z } from 'zod';

interface ToolBinding {
  name: string;
  specVersion: string;
  schema: Record<string, unknown>;
  executor: (params: unknown) => Promise<unknown>;
}

async function buildToolFromSpec(
  serviceName: string,
  specUrl: string,
  storedVersion: string | null
): Promise<{ binding: ToolBinding; changed: boolean; breaking: boolean }> {
  const spec = await fetch(specUrl).then(r => r.json());
  const currentVersion = spec.info.version as string;
  const changed = currentVersion !== storedVersion;

  // Naive breaking change heuristic: minor/patch = safe, major = escalate
  const breaking = changed && storedVersion
    ? parseInt(currentVersion.split('.')[0]) > parseInt(storedVersion.split('.')[0])
    : false;

  const binding: ToolBinding = {
    name: serviceName,
    specVersion: currentVersion,
    schema: spec, // agent framework consumes this to generate call signatures
    executor: async (params) => {
      // executor is rebuilt from spec paths at registration time
      const endpoint = resolveEndpointFromSpec(spec, params);
      return fetch(endpoint.url, { method: endpoint.method, body: JSON.stringify(params) })
        .then(r => r.json());
    }
  };

  return { binding, changed, breaking };
}

function resolveEndpointFromSpec(spec: Record<string, unknown>, params: unknown) {
  // simplified: real implementation walks spec.paths to match param shape
  const paths = spec.paths as Record<string, Record<string, { operationId: string }>>;
  const [path, methods] = Object.entries(paths)[0];
  const method = Object.keys(methods)[0];
  return { url: `${(spec.servers as {url:string}[])[0].url}${path}`, method: method.toUpperCase() };
}

// TypeScript: Agentic RAG router that selects retrieval strategy based on query shape
type RetrievalStrategy = 'flat' | 'graph' | 'agentic';

interface QueryProfile {
  requiresRelationalTraversal: boolean;
  knownEntities: string[];
  hopCount: number; // how many service boundaries likely involved
}

function classifyRetrievalStrategy(profile: QueryProfile): RetrievalStrategy {
  if (profile.hopCount > 1 || profile.requiresRelationalTraversal) {
    return profile.hopCount > 2 ? 'agentic' : 'graph';
  }
  return 'flat';
}

async function routedRetrieve(
  query: string,
  profile: QueryProfile,
  tools: { flat: (q: string) => Promise<string[]>; graph: (q: string, entities: string[]) => Promise<string[]>; agentic: (q: string) => AsyncGenerator<string> }
): Promise<string[]> {
  const strategy = classifyRetrievalStrategy(profile);

  switch (strategy) {
    case 'flat':
      return tools.flat(query);
    case 'graph':
      return tools.graph(query, profile.knownEntities);
    case 'agentic': {
      const results: string[] = [];
      for await (const chunk of tools.agentic(query)) {
        results.push(chunk);
      }
      return results;
    }
  }
}

// TypeScript: Model-agnostic agent client with local/cloud routing
import OpenAI from 'openai';

type ModelTier = 'local' | 'production';

function buildAgentClient(tier: ModelTier): OpenAI {
  const configs: Record<ModelTier, { baseURL: string; apiKey: string; model: string }> = {
    local: {
      baseURL: 'http://localhost:11434/v1', // Ollama
      apiKey: 'ollama', // required but ignored locally
      model: 'qwen2.5-coder:7b'
    },
    production: {
      baseURL: process.env.CLOUD_LLM_BASE_URL!,
      apiKey: process.env.CLOUD_LLM_API_KEY!,
      model: 'claude-opus-4-5'
    }
  };

  const config = configs[tier];
  return new OpenAI({ baseURL: config.baseURL, apiKey: config.apiKey });
}

async function runAgentTurn(
  client: OpenAI,
  model: string,
  messages: OpenAI.Chat.ChatCompletionMessageParam[],
  tools: OpenAI.Chat.ChatCompletionTool[]
) {
  const response = await client.chat.completions.create({
    model,
    messages,
    tools,
    tool_choice: 'auto'
  });

  // Audit log is identical regardless of tier — same structure, different sink
  await writeAuditEntry({
    tier: model.includes('qwen') ? 'local' : 'production',
    inputTokens: response.usage?.prompt_tokens,
    outputTokens: response.usage?.completion_tokens,
    toolCalls: response.choices[0]?.message.tool_calls?.map(tc => tc.function.name) ?? []
  });

  return response.choices[0].message;
}

async function writeAuditEntry(entry: Record<string, unknown>) {
  // write to local file in dev, postgres/S3 in prod
  console.log('[AUDIT]', JSON.stringify({ ts: new Date().toISOString(), ...entry }));
}

// TypeScript: Write-gate middleware for agent tool calls against microservices
type OperationType = 'read' | 'write' | 'delete';

interface AgentToolCall {
  toolName: string;
  operation: OperationType;
  payload: unknown;
  reasoning: string; // agent must surface why it wants to do this
}

interface GateDecision {
  approved: boolean;
  modifier?: unknown; // engineer can amend the payload before execution
  note?: string;
}

async function writeGate(
  call: AgentToolCall,
  autoApprovePolicy: (call: AgentToolCall) => boolean,
  humanReview: (call: AgentToolCall) => Promise<GateDecision>
): Promise<{ proceed: boolean; effectivePayload: unknown }> {
  if (call.operation === 'read') {
    return { proceed: true, effectivePayload: call.payload };
  }

  if (autoApprovePolicy(call)) {
    await emitAuditEvent({ ...call, gate: 'auto-approved' });
    return { proceed: true, effectivePayload: call.payload };
  }

  // Surface to engineer with reasoning — not just 'approve yes/no'
  const decision = await humanReview(call);
  await emitAuditEvent({ ...call, gate: 'human-reviewed', decision });

  return {
    proceed: decision.approved,
    effectivePayload: decision.modifier ?? call.payload
  };
}

function defaultAutoApprovePolicy(call: AgentToolCall): boolean {
  // Auto-approve low-risk writes: idempotent status updates, append-only logs
  const safeTools = new Set(['updateJobStatus', 'appendActivityLog']);
  return call.operation === 'write' && safeTools.has(call.toolName);
}

async function emitAuditEvent(event: Record<string, unknown>): Promise<void> {
  // Emit to your observability pipeline — structured for queryability
  console.log('[GATE_AUDIT]', JSON.stringify({ ts: new Date().toISOString(), ...event }));
}

// TypeScript: Domain workflow tool with typed state transitions
import { z } from 'zod';

const PolicyApplicationState = z.enum([
  'draft',
  'submitted_to_carrier',
  'carrier_review',
  'approved',
  'rejected',
  'bound'
]);
type PolicyApplicationState = z.infer<typeof PolicyApplicationState>;

const ValidTransitions: Record<PolicyApplicationState, PolicyApplicationState[]> = {
  draft: ['submitted_to_carrier'],
  submitted_to_carrier: ['carrier_review', 'rejected'],
  carrier_review: ['approved', 'rejected'],
  approved: ['bound'],
  rejected: [],
  bound: []
};

async function transitionApplicationState(
  applicationId: string,
  fromState: PolicyApplicationState,
  toState: PolicyApplicationState,
  agentReasoning: string
): Promise<{ success: boolean; error?: string }> {
  const allowed = ValidTransitions[fromState];

  if (!allowed.includes(toState)) {
    return {
      success: false,
      error: `Invalid transition: ${fromState} -> ${toState}. Allowed: ${allowed.join(', ')}`
    };
  }

  // Agent must provide reasoning for audit — not optional
  await emitAuditEvent({
    applicationId,
    fromState,
    toState,
    agentReasoning,
    ts: new Date().toISOString()
  });

  // Actual service call — only reached after transition validation
  const response = await fetch(`/api/applications/${applicationId}/state`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ state: toState })
  });

  return { success: response.ok };
}

async function emitAuditEvent(event: Record<string, unknown>): Promise<void> {
  console.log('[DOMAIN_AUDIT]', JSON.stringify(event));
}