Local Agent HTTP Server

A local Agent can be called directly in-process, but it can also expose service endpoints.

Recommended startup path

The recommended entry is the unified lifecycle API:

const started = await agent.start({
  http: {
    host: "127.0.0.1",
    port: 15314,
  },
});

console.log(started.http?.baseUrl);

This starts the following in one place:

• the HTTP server
• plugin lifecycles by default

Start HTTP only

const started = await agent.start({
  http: {
    host: "127.0.0.1",
    port: 15314,
  },
});

console.log(started.http?.baseUrl);

The current default port is 15314.

If you do not specify a port manually, this is the default local SDK HTTP listener port.

start() vs not calling start()

If you do not call agent.start():

• you can still call await agent.createSession() and then use session.prompt() / session.subscribe()
• this is the right shape when you use the Agent as a local in-process library
• no HTTP server starts
• no background plugin lifecycle starts

After you call agent.start():

• the Agent exposes HTTP endpoints
• plugins start by default
• chat, task, ActionSchedule, and other background loops can keep running

A simple mental model is:

• no start: library mode
• start: long-lived runtime mode

When to use HTTP

• another process should call the agent through RemoteAgent
• you want to expose the local agent as a lightweight service

This is especially useful when the caller and the executor live in different processes.

What happens before startup

When you call agent.start({ http: { ... } }), the SDK starts plugins first by default.

That reduces the risk of ending up in a state where the endpoint is up but a critical plugin is still not ready.

Related docs

• RemoteAgent quickstart
• SDK HTTP endpoints