Artifacts

Agents produce things that people use: an API, a web front-end, a report to download, live progress to watch. Golem calls these artifacts and serves them from the same deployment as the agents, so an application needs no separate web server, file host, or streaming service. A single golem deploy ships the agents, their tools, and the front-end whose buttons call them.

For example, a reporting application deploys its single-page front-end as static files. The front-end’s buttons call HTTP endpoints on ReportAgent agents, progress streams back to the page while the agent works, and the finished report, a file the agent wrote, is served from the agent’s filesystem. The front-end, the API, the stream, and the file all come from one deployment, and the agents behind them are durable.

HTTP endpoints for agent methods

An agent type can declare an HTTP mount path, and its methods can declare endpoints under it. The mount path contains every constructor parameter, so the URL identifies the agent. With this declaration, POST /counters/alice/increment calls increment on CounterAgent("alice"):

export const CounterAgent = defineAgent({
  name: "CounterAgent",
  id: { name: z.string() },
  http: http.mount("/counters/{name}"),
  methods: {
    increment: method({
      input: {},
      returns: z.number(),
      http: http.post("/increment"),
    }),
  },
});

export const CounterAgent = defineAgent({
  name: "CounterAgent",
  mode: "durable",
  id: { name: Schema.String },
  http: Http.mount("/counters/{name}"),
  methods: {
    increment: method({
      input: {},
      success: Schema.Number,
      http: [Http.post("/increment")],
    }),
  },
});

#[agent_definition(mount = "/counters/{name}")]
pub trait CounterAgent {
    fn new(name: String) -> Self;
 
    #[endpoint(post = "/increment")]
    fn increment(&mut self) -> u32;
}

@agentDefinition(mount = "/counters/{name}")
trait CounterAgent extends BaseAgent {
  class Id(val name: String)
 
  @endpoint(method = "POST", path = "/increment")
  def increment(): Future[Int]
}

#derive.agent
#derive.mount("/counters/{name}")
struct CounterAgent {
  name : String
  mut value : UInt64
}
 
fn CounterAgent::new(name : String) -> CounterAgent {
  { name, value: 0 }
}
 
#derive.endpoint(post="/increment")
pub fn CounterAgent::increment(self : Self) -> UInt64 {
  self.value += 1
  self.value
}

type ID struct{ Name string }
 
var Agent = golem.DefineAgent[ID](golem.Spec{
	Name: "CounterAgent",
	HTTP: &golem.Mount{Path: "/counters/{name}"},
})
 
var Increment = Agent.Method[golem.Unit, int64]("increment", golem.HTTP(golem.POST("/increment")))

Path, query, and header parameters map to method inputs, and return values map to responses. Each deployment publishes an OpenAPI document for its endpoints. A deployment can claim a subdomain, such as my-app.localhost:9006 locally or my-app.apps.golem.cloud on Golem Cloud.

HTTP routers

When an application needs full control over HTTP, for example to serve an existing web framework or handle streaming uploads, it can define an HTTP router. A router’s handler receives a standard Fetch Request and returns a Response:

export const EchoRouter = defineHttpRouter("EchoRouter")
  .mount("/echo")
  .implement((request) => new Response(request.body));

const routes = Routes.add("POST", "/", Effect.gen(function* () {
  const request = yield* HttpServerRequest.HttpServerRequest;
  return HttpServerResponse.stream(request.stream);
}));
 
HttpRouter.define("EchoRouter", {
  mount: Http.mount("/echo"),
}).implement(Routes.toHttpEffect(routes));

struct EchoRouter;
 
#[http_router(name = "EchoRouter", mount = "/echo")]
impl HttpRouter for EchoRouter {
    type Config = ();
 
    fn new(_: Config<()>) -> Self {
        Self
    }
 
    async fn handle(&self, request: HttpRequest) -> HttpResponse {
        HttpResponse { status: 200, headers: vec![], body: request.body }
    }
}

@httpRouter(typeName = "EchoRouter", mount = "/echo")
trait EchoRouter extends BaseAgent {
  @httpHandler def serve(request: HttpRequest): Future[HttpResponse]
}
 
@agentImplementation()
final class EchoRouterImpl extends EchoRouter {
  def serve(request: HttpRequest): Future[HttpResponse] =
    Future.successful(HttpResponse(UShort(200), Nil, request.body))
}

#derive.http_router
#derive.mount("/echo")
struct EchoRouter {}
 
fn EchoRouter::new() -> EchoRouter { EchoRouter::{ } }
 
#derive.http_handler
pub fn EchoRouter::serve(_self : Self, request : @http.HttpRequest) -> @http.HttpResponse {
  let input = request.body
  {
    status: 200,
    headers: [],
    body: @schema.AgentStream::produce(
      async fn(writer) {
        defer input.drop()
        for ;; {
          match input.read() {
            None => return
            Some(chunk) =>
              if writer.write_one(chunk) is @schema.PeerDropped { return }
          }
        }
      },
      on_unstarted_drop=() => input.drop(),
    ),
  }
}

var EchoRouter = golem.DefineHTTPRouter(golem.RouterSpec{Name: "EchoRouter", Mount: "/echo"})
 
func init() {
	EchoRouter.Handle(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_, _ = io.Copy(w, r.Body)
	}))
}

A router calls agents through their clients, so one router can serve a single-page app while typed endpoints answer its API calls on the same origin.

Interactive apps

A web app on Golem is interactive, not static output: its JavaScript runs in the browser and calls the agents’ HTTP endpoints, and each call runs durable agent code with the agent’s state and permissions. An agent can also generate an app at runtime: it writes HTML and JavaScript into its own filesystem, serves them as live files, and the page calls the agent’s endpoints. What Golem does not run is a long-lived server process, such as a development server, inside a tool.

Static and live files

A live file is never served half-written: the read waits until the agent’s current method call finishes.

Cached read-only responses

Methods marked read-only can be answered from a cache without loading the agent. On a GET endpoint, the response carries an ETag, and a client that already has the current version gets 304 Not Modified.

Streams that survive reconnects

A method that returns a stream, mounted on an HTTP endpoint, is served using the Durable Streams protocol, an open HTTP protocol for resumable streams. The stream belongs to the agent, not to the HTTP connection, so a browser tab that reloads continues from the last position it read. Existing Durable Streams clients work with these endpoints.

Login

Endpoints can require authentication. A single-page app can sign users in with the OAuth2 authorization code flow with PKCE, and Golem checks the token before any agent code runs.

Keeping an existing web app

You do not have to serve your front-end from Golem. An existing application, such as a Next.js app, can call agents from its server through a client library generated for its language or through the REST API, and keep its own UI and hosting.

One agent, many entry points

The same agent can be reached from a browser, an MCP client, the CLI, a generated client library in your own application, the REST API, and other agents. Endpoints are declared in agent code, and they become reachable over HTTP or MCP only when an httpApi or mcp deployment in golem.yaml publishes them.

Open full-size image in a new tab.Open full-size image in a new tab.

Next

Agent lifecycle: how agents are created, suspended, updated, inspected, and scaled.

Related guides:

• Making custom APIs
• HTTP routers and files
• Durable Streams
• MCP