Exposing Agents via API

Introduction: Why Expose Agents via APIs?

Think about how you use your favorite apps: checking email on your phone, responding from your laptop, or asking your smart speaker to read messages. Each device talks to the same service through an API . This is the power of decoupling — separating core logic from any single interface so it can be accessed from anywhere. In this course, we'll put three of those factors into practice by building a real API layer around an AI agent . Specifically, this lesson kicks off Factor 11 — Trigger from anywhere, meet users where they are, and expands Factor 6 — Launch / Pause / Resume with simple APIs by implementing the launch part. We'll build an Express server that exposes an AI agent through REST endpoints, making it accessible from web browsers, mobile apps, scripts, or any tool that can make HTTP requests. The server logic lives in app.ts, the entry point that starts listening lives in main.ts, and agent runs are kicked off as background async work using void runAgentInBackground(...) .

Project Structure

As we transition from building standalone agent logic to exposing it via a web service, our project structure reflects a clear separation between the API layer and the core logic . You are already familiar with the core directory, which houses the agent's decision-making logic, tools, and models. We now introduce a server directory to handle web requests and a top-level test.ts script to simulate a client: text . ├── src/ │ ├── server/ │ │ ├── app.ts # Express app: /agent/launch and /agent/state/:stateId │ │ └── main.ts # Entry point: starts the HTTP server │ └── core/ # Core agent logic (agent, models, tools, prompts, utils) └── test.ts # Simple client script that launches + polls state src/core/ : Contains the Agent class and State models you've used in previous lessons. src/server/app.ts : This is where the Express application is configured. It imports the agent from core and exposes it through REST endpoints. src/server/main.ts : The entry point that imports app from app.ts and calls app.listen(...) to start accepting connections. test.ts : A standalone script that uses the built-in fetch API to talk to your server, allowing you to test the full lifecycle of an agent task. This separation is central to Factor 11 : your agent logic remains independent of how it is triggered — whether it's via a CLI, a web API, a Slack bot, or a cron job. The server directory is just one thin adapter around a stable core.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Turning Errors into JSON Responses

Before we start validating input, we need a consistent way to report failures back to the client. When something goes wrong — a malformed request body, a missing record — we want the client to receive a structured JSON response with the right HTTP status code, not a generic server crash. Two small pieces make this happen: a custom HttpError class and a global error-handling middleware.

HttpError is a tiny subclass of Error that carries an HTTP status code alongside its message, so any route can express both "what went wrong" and "which status the client should receive":

TypeScript

export class HttpError extends Error {
  constructor(
    readonly statusCode: number,
    message: string
  ) {
    super(message);
  }
}

export class HttpError extends Error {
  constructor(
    readonly statusCode: number,
    message: string
  ) {
    super(message);
  }
}

In Express, an error thrown inside a synchronous route handler is automatically caught and forwarded to a special error-handling middleware — one that takes four parameters instead of the usual three. We register it after all the routes so it acts as a catch-all:

TypeScript

app.use((error: unknown, _request: Request, response: Response, _next: NextFunction) => {
  const statusCode = error instanceof HttpError ? error.statusCode : 500;
  const message = error instanceof Error ? error.message : String(error);
  response.status(statusCode).json({ detail: message });
});

app.use((error: unknown, _request: Request, response: Response, _next: NextFunction) => {
  const statusCode = error instanceof HttpError ? error.statusCode : 500;
  const message = error instanceof Error ? error.message : String(error);
  response.status(statusCode).json({ detail: message });
});

When the error is an HttpError, the middleware uses its statusCode; anything else falls back to 500. The payoff is that any route can simply throw new HttpError(400, "input_prompt must be a non-empty string") and trust that the client receives { "detail": "input_prompt must be a non-empty string" } with status 400. Every failure flows through this one place and comes back as predictable JSON.

Note: This automatic forwarding applies to synchronous throws. All our route handlers in this unit are synchronous — they kick off long-running work in the background rather than awaiting it — so a plain throw is enough here. In the next unit, once handlers begin to await database and agent calls, you'll add a small wrapper so asynchronous errors reach this same middleware too.

Building the Launch Endpoint Structure

The launch endpoint is where clients start a new agent workflow. This is the first piece of Factor 6 — giving external systems a simple API to launch agent execution:

TypeScript

import { randomUUID } from "node:crypto";

app.post("/agent/launch", (request: Request, response: Response) => {
  const inputPrompt = requireStringField(request.body, "input_prompt");

  const initialState: State = {
    id: randomUUID(),          // Generate a unique identifier
    steps: 0,
    status: "running",
    context: [{ role: "user", content: inputPrompt }],
    pending_tool_calls: [],
    error: null,
    final_answer: null
  };

  // Store the state before background work starts so clients can poll immediately
  states.set(initialState.id, initialState);
  void runAgentInBackground(initialState.id);

  response.json(initialState);
});

import { randomUUID } from "node:crypto";

app.post("/agent/launch", (request: Request, response: Response) => {
  const inputPrompt = requireStringField(request.body, "input_prompt");

  const initialState: State = {
    id: randomUUID(),          // Generate a unique identifier
    steps: 0,
    status: "running",
    context: [{ role: "user", content: inputPrompt }],
    pending_tool_calls: [],
    error: null,
    final_answer: null
  };

  // Store the state before background work starts so clients can poll immediately
  states.set(initialState.id, initialState);
  void runAgentInBackground(initialState.id);

  response.json(initialState);
});

app.post("/agent/launch", ...) registers the handler for POST requests to that path. randomUUID() from Node's built-in crypto module generates a collision-resistant unique ID. The initial State is stored immediately, and the background helper is triggered with void runAgentInBackground(...). Using void signals explicitly that the returned Promise is intentionally not awaited — the response is sent back to the client right away while the agent runs in the background. Because the handler is synchronous, any HttpError thrown by requireStringField is caught by Express and forwarded to the error middleware.

Introduction: Why Expose Agents via APIs?

Project Structure

Join the 1M+ learners on CodeSignal

Setting Up Express

Turning Errors into JSON Responses

Defining the Launch Request Validation

Understanding the State Model

Managing State with In-Memory Storage

Creating the Agent Instance

Building the Launch Endpoint Structure

Implementing Background Task Execution

Creating the State Retrieval Endpoint

Setting Up the Test Script

Implementing the Polling Loop

Viewing the Complete Output

Summary and What's Next