The Agent Stack Just Grew Up: What the Latest AI & Agent News Means for Your Architecture

┌──────────────┐   gen_ai spans   ┌──────────────┐
│  API / UI    ├─────────────────▶│  Agent Runtime│
└──────────────┘                  │  (budgeted)   │
                                  └───────┬───────┘
         ┌────────────────────────────────┼─────────────────┐
         ▼                                ▼                 ▼
  ┌─────────────┐                 ┌──────────────┐   ┌──────────────┐
  │ Model Client│                 │ Tool Registry│   │ MCP Gateway  │
  │ (retry/OTel)│                 │ (zod + scope)│   │ (OAuth 8707) │
  └─────────────┘                 └──────┬───────┘   └──────┬───────┘
                                         ▼                  ▼
                                  ┌──────────────────────────────┐
                                  │ Sandboxed tool workers       │
                                  │ (egress allowlist, no net)   │
                                  └──────────────────────────────┘

// src/agent/contracts.ts
import { z } from "zod";

export type ToolRisk = "read" | "write" | "destructive";

export interface ToolContext {
  runId: string;
  tenantId: string;
  actor: { sub: string; scopes: ReadonlySet<string> };
  signal: AbortSignal;
}

export interface ToolDefinition<S extends z.ZodTypeAny, R extends z.ZodTypeAny> {
  name: string;
  description: string;
  risk: ToolRisk;
  input: S;
  output: R;
  timeoutMs: number;
  requiredScope: string;
  execute(args: z.infer<S>, ctx: ToolContext): Promise<z.infer<R>>;
}

export class ToolError extends Error {
  constructor(
    message: string,
    readonly code: string,
    readonly retryable: boolean,
    readonly hint?: string,
  ) {
    super(message);
    this.name = "ToolError";
  }
}

// src/agent/registry.ts
import { z } from "zod";
import { ToolError, type ToolContext, type ToolDefinition } from "./contracts";

const MAX_OBSERVATION_BYTES = 8_000;

function truncate(s: string, limit: number): string {
  return s.length <= limit ? s : `${s.slice(0, limit)}…[truncated ${s.length - limit} chars]`;
}

export class ToolRegistry {
  private readonly tools = new Map<string, ToolDefinition<any, any>>();

  register<S extends z.ZodTypeAny, R extends z.ZodTypeAny>(tool: ToolDefinition<S, R>): void {
    if (this.tools.has(tool.name)) throw new Error(`Duplicate tool registration: ${tool.name}`);
    this.tools.set(tool.name, tool);
  }

  /** Only tools the actor may use are ever shown to the model. */
  manifestFor(ctx: ToolContext) {
    return [...this.tools.values()]
      .filter((t) => ctx.actor.scopes.has(t.requiredScope))
      .map((t) => ({ name: t.name, description: t.description, input_schema: z.toJSONSchema(t.input) }));
  }

  async invoke(name: string, rawArgs: unknown, ctx: ToolContext): Promise<string> {
    const tool = this.tools.get(name);
    if (!tool) return JSON.stringify({ error: "unknown_tool", tool: name });
    if (!ctx.actor.scopes.has(tool.requiredScope)) {
      return JSON.stringify({ error: "insufficient_scope", tool: name, required: tool.requiredScope });
    }

    const parsed = tool.input.safeParse(rawArgs);
    if (!parsed.success) {
      return JSON.stringify({ error: "invalid_arguments", issues: parsed.error.issues });
    }

    const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(tool.timeoutMs)]);
    try {
      const result = await tool.execute(parsed.data, { ...ctx, signal });
      return truncate(JSON.stringify(tool.output.parse(result)), MAX_OBSERVATION_BYTES);
    } catch (err) {
      // Never throw into the loop: a structured observation lets the model recover.
      const e = err instanceof ToolError ? err : new ToolError("tool_failed", "unhandled", false);
      return JSON.stringify({ error: e.code, message: e.message, retryable: e.retryable, hint: e.hint });
    }
  }
}

// src/agent/loop.ts
import { trace, SpanStatusCode } from "@opentelemetry/api";
import type { ToolRegistry } from "./registry";
import type { ToolContext } from "./contracts";

const tracer = trace.getTracer("agent-runtime", "1.0.0");

export interface RunBudget {
  maxSteps: number;
  maxToolCalls: number;
  maxWallClockMs: number;
}

export interface AgentRunResult {
  status: "completed" | "budget_exhausted" | "aborted";
  finalText?: string;
  steps: number;
  toolCalls: number;
}

export async function runAgent(
  model: ModelClient,
  registry: ToolRegistry,
  ctx: ToolContext,
  budget: RunBudget,
): Promise<AgentRunResult> {
  return tracer.startActiveSpan("invoke_agent", async (span) => {
    span.setAttributes({
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.name": "support-triage",
      "agent.run_id": ctx.runId,
    });

    const deadline = Date.now() + budget.maxWallClockMs;
    const messages = await buildPrompt(ctx);
    let toolCalls = 0;

    const done = (r: AgentRunResult): AgentRunResult => {
      span.setAttributes({ "agent.status": r.status, "agent.steps": r.steps, "agent.tool_calls": r.toolCalls });
      span.setStatus({ code: r.status === "completed" ? SpanStatusCode.OK : SpanStatusCode.ERROR });
      span.end();
      return r;
    };

    try {
      for (let step = 1; step <= budget.maxSteps; step++) {
        if (Date.now() > deadline) return done({ status: "budget_exhausted", steps: step - 1, toolCalls });

        const res = await model.complete({ messages, tools: registry.manifestFor(ctx), signal: ctx.signal });
        span.addEvent("gen_ai.usage", { input_tokens: res.usage.inputTokens, output_tokens: res.usage.outputTokens });
        messages.push(res.message);

        if (res.stopReason !== "tool_use") {
          return done({ status: "completed", finalText: res.text, steps: step, toolCalls });
        }

        for (const call of res.toolCalls) {
          toolCalls += 1;
          if (toolCalls > budget.maxToolCalls) {
            return done({ status: "budget_exhausted", steps: step, toolCalls });
          }
          const observation = await tracer.startActiveSpan(
            `execute_tool ${call.name}`,
            { attributes: { "gen_ai.tool.name": call.name, "gen_ai.tool.call_id": call.id } },
            async (toolSpan) => {
              const out = await registry.invoke(call.name, call.input, ctx);
              toolSpan.end();
              return out;
            },
          );
          messages.push({ role: "tool", toolCallId: call.id, content: observation });
        }
      }
      return done({ status: "budget_exhausted", steps: budget.maxSteps, toolCalls });
    } catch (err) {
      span.recordException(err as Error);
      return done({ status: "aborted", steps: 0, toolCalls });
    }
  });
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

// Audience-bound token (RFC 8707): this token is useless against any other resource.
const transport = new StreamableHTTPClientTransport(new URL("https://tools.internal/mcp"), {
  requestInit: { headers: { Authorization: `Bearer ${await mintToken({ aud: "https://tools.internal/mcp", scopes: ["tickets:read"] })}` } },
});

const client = new Client({ name: "agent-runtime", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);
const { tools } = await client.listTools(); // pin and diff this list in CI