@cuylabs/agent-foundry-agentserver-invocations

TypeScript counterpart to Python azure-ai-agentserver-invocations.

This is the low-level Foundry Agent Server Invocations protocol host. It does not depend on @cuylabs/agent-core; consumers can implement a raw InvocationHandler and serve the hosted-agent /invocations contract directly. Use @cuylabs/agent-foundry-hosting when you want the higher-level @cuylabs/agent-core adapter.

Install

npm install @cuylabs/agent-foundry-agentserver-invocations express

Quick Start

import {
  InvocationHandler,
  runInvocationsServer,
  type InvocationContext,
} from "@cuylabs/agent-foundry-agentserver-invocations";
import type { Request, Response } from "express";

class HelloHandler extends InvocationHandler {
  async handle(_req: Request, res: Response, ctx: InvocationContext) {
    res.setHeader("Content-Type", "text/event-stream");
    res.write(`data: ${JSON.stringify({ type: "token", content: "hello" })}\n\n`);
    res.write(
      `data: ${JSON.stringify({
        type: "done",
        invocation_id: ctx.invocationId,
        session_id: ctx.sessionId,
        full_text: "hello",
      })}\n\n`,
    );
    res.end();
  }
}

await runInvocationsServer({
  handler: () => new HelloHandler(),
  port: 8088,
});

HTTP Surface

| Method | Path | Description | | --- | --- | --- | | POST | /invocations | Invoke the agent | | GET | /invocations/{invocationId} | Optional LRO status | | DELETE | /invocations/{invocationId} | Optional LRO cancel | | POST | /invocations/{invocationId}/cancel | Optional cancel alias used by Foundry HITL samples | | GET | /invocations/docs/openapi.json | OpenAPI spec | | GET | /healthz | Liveness probe | | GET | /readiness | Foundry readiness probe | | GET | /readyz | Readiness alias |

/readiness and /readyz return the Python-compatible readiness body:

{ "status": "healthy" }

Operations

The host mirrors the Python request-span lifecycle for the Invocations protocol. It creates OpenTelemetry server spans named invoke_agent, get_invocation, and cancel_invocation, propagates invocation/session IDs as baggage, records handler errors on the active span, and ends streaming spans only after the HTTP response finishes or the client disconnects.

By default, runInvocationsServer() also logs startup configuration and drains in-flight requests for 30 seconds during close() before forcing sockets closed. Pass gracefulShutdownTimeoutSeconds to tune that behavior, or configureObservability: false if the containing application owns exporter initialization itself.

Python Mapping

This package maps to:

azure-ai-agentserver-invocations

It intentionally does not map to:

agent-framework-foundry-hosting

That higher layer is represented by @cuylabs/agent-foundry-hosting.