Adding HTTP Endpoints to a TypeScript Golem Agent

Overview

Golem agents can be exposed over HTTP using code-first route definitions. This involves:

Adding a mount path to the @agent() decorator
Annotating methods with @endpoint()
Adding an httpApi deployment section to golem.yaml (See the golem-configure-api-domain guide)

Guide	Description
`golem-http-params-ts`	Path/query/header variable mapping, body mapping, supported types, response mapping
`golem-make-http-request-ts`	Making outgoing HTTP requests from agent code, especially when calling other Golem agent endpoints (required for correct JSON body formatting)
`golem-add-http-auth-ts`	Enabling authentication and receiving `Principal`
`golem-add-cors-ts`	Configuring CORS allowed origins
`golem-configure-api-domain`	Setting up `httpApi` in `golem.yaml`, security schemes, domain deployments

Steps

Add mount to the @agent() decorator
Add @endpoint() decorators to methods
Add httpApi deployment to golem.yaml (see golem-configure-api-domain guide)
Build and deploy

Mount Path

The mount option on @agent() defines the base HTTP path. Path variables in {braces} map to constructor parameters:


import { BaseAgent, agent, endpoint } from '@golemcloud/golem-ts-sdk';
 
@agent({
  mount: '/api/tasks/{name}',
})
class TaskAgent extends BaseAgent {
  constructor(readonly name: string) {
    super();
  }
  // ...
}

Rules:

Path must start with /
Every constructor parameter must appear as a {variable} in the mount path (or be mapped via mount-level headers)
Every {variable} must match a constructor parameter name
Catch-all {*rest} variables are not allowed in mount paths

Endpoint Decorator

The @endpoint() decorator marks a method as an HTTP endpoint. Specify exactly one HTTP method (get, post, put, delete, or custom):


@endpoint({ get: '/items' })
async listItems(): Promise<Item[]> { ... }
 
@endpoint({ post: '/items' })
async createItem(name: string, count: number): Promise<Item> { ... }
 
@endpoint({ put: '/items/{id}' })
async updateItem(id: string, name: string): Promise<Item> { ... }
 
@endpoint({ delete: '/items/{id}' })
async deleteItem(id: string): Promise<void> { ... }
 
@endpoint({ custom: { method: 'PATCH', path: '/items/{id}' } })
async patchItem(id: string, patch: PatchData): Promise<Item> { ... }

Endpoint paths are relative to the mount path. A method can have multiple @endpoint() decorators to expose it under different routes.

For details on how path variables, query parameters, headers, and request bodies map to method parameters, See the golem-http-params-ts guide.

Phantom Agents

Set phantom: true on the agent to create a new ephemeral agent instance for each HTTP request. This enables fully parallel request processing:


@agent({
  mount: '/gateway/{name}',
  phantom: true
})
class GatewayAgent extends BaseAgent {
  constructor(readonly name: string) { super(); }
  // Each HTTP request gets its own agent instance
}

Complete Example


import { BaseAgent, agent, endpoint, Result } from '@golemcloud/golem-ts-sdk';
 
type Task = { id: string; title: string; done: boolean };
 
@agent({ mount: '/task-agents/{name}' })
class TaskAgent extends BaseAgent {
  private tasks: Task[] = [];
 
  constructor(readonly name: string) {
    super();
  }
 
  @endpoint({ get: '/tasks' })
  async getTasks(): Promise<Task[]> {
    return this.tasks;
  }
 
  @endpoint({ post: '/tasks' })
  async createTask(title: string): Promise<Task> {
    const task: Task = { id: String(this.tasks.length + 1), title, done: false };
    this.tasks.push(task);
    return task;
  }
 
  @endpoint({ get: '/tasks/{id}' })
  async getTask(id: string): Promise<Task | undefined> {
    return this.tasks.find(t => t.id === id);
  }
 
  @endpoint({ post: '/tasks/{id}/complete' })
  async completeTask(id: string): Promise<Result<Task, { error: string }>> {
    const task = this.tasks.find(t => t.id === id);
    if (!task) return Result.err({ error: 'not found' });
    task.done = true;
    return Result.ok(task);
  }
}


# golem.yaml (add to existing file)
httpApi:
  deployments:
    local:
    - domain: my-app.localhost:9006
      agents:
        TaskAgent: {}

Key Constraints

A mount path is required on @agent() before any @endpoint() decorators can be used
All constructor parameters must be provided via mount path variables or header variables
Path/query/header variable names must exactly match method parameter names
Catch-all path variables {*name} can only appear as the last path segment
The endpoint path must start with /
Exactly one HTTP method must be specified per @endpoint() decorator