AgentHTTP

AgentHTTP is the HTTP transport for a local Agent. It exposes the agent's session and control surfaces over HTTP endpoints, making it accessible from browser clients, curl, or any HTTP-capable tool.

Only available when you install @downcity/server:

pnpm add @downcity/server

Minimal usage

import { AgentHTTP } from "@downcity/server";
import { Agent } from "@downcity/agent";

const agent = new Agent({ id: "demo", path: process.cwd() });
const http = new AgentHTTP(agent);

const binding = await http.server().listen({ host: "127.0.0.1", port: 5314 });
// HTTP server listening on http://127.0.0.1:5314

Constructor

new AgentHTTP(agent: Agent)

Methods

listen(options)

Start the HTTP server.

const binding = await http.server().listen({
  host: "127.0.0.1",  // optional: bind address (default: "127.0.0.1")
  port: 5314,            // required: TCP port
});

Returns AgentHttpBinding with server info, and AgentHttpServerHandle which you can use to read the raw Hono app for custom route additions.

close()

Stop the HTTP server.

await http.close();

Endpoints

The HTTP server exposes a RESTful interface for session management, execution, and health checks. For the exact route table, see HTTP Endpoints.

When to use it

• You want to access an agent session from a browser or mobile app
• You are building a local dev server with an agent backend
• You need to integrate with HTTP middleware or existing web infrastructure

See also: AgentRPC for the lightweight RPC transport.