rust-soham/golem-claw/golem-annotate-agent-ts

Annotating Agents and Methods (TypeScript)

Overview

Golem agents can annotate the agent class and its methods with @prompt() and @description() decorators. These provide metadata for AI/LLM tool discovery — agents with annotations can be used as tools by LLM-based systems.

Annotations

• `@prompt("...")` — A short instruction telling an LLM when to call this method
• `@description("...")` — A longer explanation of what the agent or method does, its parameters, and return value

Agent-Level Annotations

To describe the agent itself (its overall purpose), apply @description() as a standalone class-level decorator alongside @agent(). Do NOT pass description as a property inside the @agent() options — AgentDecoratorOptions does not accept it, and it will cause a TypeScript compilation error.

// ✅ Correct — @description is a separate class decorator
@agent({ mount: "/api/v1/profiles" })
@description("Handles user profile management and preferences")
class ProfileAgent extends BaseAgent { ... }
// ❌ Wrong — description is not a valid @agent() option
@agent({ mount: "/api/v1/profiles", description: "..." })
class ProfileAgent extends BaseAgent { ... }

Method-Level Annotations

import { BaseAgent, agent, prompt, description } from '@golemcloud/golem-ts-sdk';
@agent({ mount: "/warehouses/{warehouseId}" })
@description("Manages product inventory for a warehouse")
class InventoryAgent extends BaseAgent {
    constructor(warehouseId: string) {
        super();
    }
    @prompt("Look up the current stock level for a product")
    @description("Returns the number of units in stock for the given product SKU. Returns 0 if the product is not found.")
    async checkStock(sku: string): Promise<number> {
        // ...
    }
    @prompt("Add units of a product to inventory")
    @description("Increases the stock count for the given SKU by the specified amount. Returns the new total.")
    async restock(sku: string, quantity: number): Promise<number> {
        // ...
    }
    @prompt("Remove units of a product from inventory")
    @description("Decreases the stock count for the given SKU. Throws if insufficient stock.")
    async pick(sku: string, quantity: number): Promise<number> {
        // ...
    }
}

Guidelines

• @description() on the class describes the agent's overall purpose for LLM discovery
• @prompt() on a method should be a natural-language instruction an LLM can match against a user request
• @description() on a method should document behavior, edge cases, and expected inputs/outputs
• Both decorators are optional — omit them for internal methods not intended for LLM discovery
• Annotations have no effect on runtime behavior; they are purely metadata
• Never pass description as a property of the @agent() decorator options — always use the standalone @description() decorator