golem-add-http-endpoint-scala

Add a mount parameter to @agentDefinition defining the base path, annotate trait methods with @endpoint(method, path), then add an httpApi deployment section to golem.yaml. Build and deploy to make the routes live.

Path variables in the mount path must exactly match the class Id constructor parameter names, including casing. Use camelCase identifiers like {taskName}, never kebab-case like {task-name}, and every constructor parameter must appear in the path.

Future[Unit] returns 204 No Content, Future[T] returns 200 OK with JSON, Future[Option[T]] returns 404 when None, and Future[Either[E, T]] returns 500 on Left. This mapping is currently not configurable.

Yes, but all custom types used in endpoint parameters and return values must have a zio.blocks.schema.Schema instance, typically via derives Schema in Scala 3. Use List[T] instead of Array[T], since Array lacks automatic Schema derivation.

Setting phantomAgent = true on @agentDefinition creates a new agent instance for each HTTP request, enabling fully parallel request processing. It is useful for stateless handlers like webhooks.

The @agentDefinition and @endpoint annotations are macros that require the scalacOptions += "-experimental" flag in your build. Also verify the endpoint path starts with / and a mount path exists before using @endpoint.