@loopstack/agent-examples 0.1.1

package/dist/workflows/custom-agent/custom-agent-example.workflow.d.ts

@@ -0,0 +1,30 @@
+import { BaseWorkflow } from '@loopstack/common';
+import type { TransitionInput } from '@loopstack/common';
+import type { LlmDelegateResult, LlmGenerateTextResult } from '@loopstack/llm-provider-module';
+import { LlmDelegateToolCallsTool, LlmGenerateTextTool, LlmUpdateToolResultTool } from '@loopstack/llm-provider-module';
+interface CustomAgentState {
+    llmResult?: LlmGenerateTextResult;
+    delegateResult?: LlmDelegateResult;
+    turnCount: number;
+}
+export declare class CustomAgentExampleWorkflow extends BaseWorkflow {
+    private readonly llmGenerateText;
+    private readonly llmDelegateToolCalls;
+    private readonly llmUpdateToolResult;
+    constructor(llmGenerateText: LlmGenerateTextTool, llmDelegateToolCalls: LlmDelegateToolCallsTool, llmUpdateToolResult: LlmUpdateToolResultTool);
+    setup(_state: CustomAgentState): Promise<void>;
+    llmTurn(state: CustomAgentState): Promise<void>;
+    notifyOverBudget(_state: CustomAgentState): Promise<void>;
+    wrapUp(_state: CustomAgentState): Promise<void>;
+    executeToolCalls(state: CustomAgentState): Promise<void>;
+    toolResultReceived(state: CustomAgentState, input: TransitionInput): Promise<void>;
+    toolsComplete(_state: CustomAgentState): void;
+    respond(_state: CustomAgentState): void;
+    private hasBudget;
+    private isOverBudget;
+    private hasToolCalls;
+    private allToolsComplete;
+    private isEndTurn;
+}
+export {};
+//# sourceMappingURL=custom-agent-example.workflow.d.ts.map

package/dist/workflows/custom-agent/custom-agent-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-agent-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/custom-agent/custom-agent-example.workflow.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAiD,MAAM,mBAAmB,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC/F,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EAEnB,uBAAuB,EACxB,MAAM,gCAAgC,CAAC;AAIxC,UAAU,gBAAgB;IACxB,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,cAAc,CAAC,EAAE,iBAAiB,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAcD,qBAKa,0BAA2B,SAAQ,YAAY;IAExD,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IACrC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;gBAFnB,eAAe,EAAE,mBAAmB,EACpC,oBAAoB,EAAE,wBAAwB,EAC9C,mBAAmB,EAAE,uBAAuB;IAUzD,KAAK,CAAC,MAAM,EAAE,gBAAgB;IA0B9B,OAAO,CAAC,KAAK,EAAE,gBAAgB;IA2B/B,gBAAgB,CAAC,MAAM,EAAE,gBAAgB;IAezC,MAAM,CAAC,MAAM,EAAE,gBAAgB;IAoB/B,gBAAgB,CAAC,KAAK,EAAE,gBAAgB;IAcxC,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe;IAcxE,aAAa,CAAC,MAAM,EAAE,gBAAgB;IAStC,OAAO,CAAC,MAAM,EAAE,gBAAgB;IAGhC,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,SAAS;CAGlB"}

package/dist/workflows/custom-agent/custom-agent-example.workflow.js

@@ -0,0 +1,165 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomAgentExampleWorkflow = void 0;
+const node_path_1 = require("node:path");
+const common_1 = require("@loopstack/common");
+const llm_provider_module_1 = require("@loopstack/llm-provider-module");
+const MAX_TURNS = 2;
+let CustomAgentExampleWorkflow = class CustomAgentExampleWorkflow extends common_1.BaseWorkflow {
+    llmGenerateText;
+    llmDelegateToolCalls;
+    llmUpdateToolResult;
+    constructor(llmGenerateText, llmDelegateToolCalls, llmUpdateToolResult) {
+        super();
+        this.llmGenerateText = llmGenerateText;
+        this.llmDelegateToolCalls = llmDelegateToolCalls;
+        this.llmUpdateToolResult = llmUpdateToolResult;
+    }
+    async setup(_state) {
+        await this.documentStore.save(common_1.MarkdownDocument, {
+            markdown: '# Custom Agent Example\n\n' +
+                `This agent has a budget of **${MAX_TURNS} tool-using turns**. ` +
+                'Once the budget is hit, the workflow forces a final summary turn with no tools available.',
+        });
+        await this.documentStore.save(llm_provider_module_1.LlmMessageDocument, {
+            role: 'user',
+            text: 'I want to travel somewhere warm. Find me the first city of at least 25°C from this list, ' +
+                'trying them one at a time in order: London, New York, Paris, Berlin, Tokyo. ' +
+                'After each lookup, decide based on the temperature whether to keep searching.',
+        });
+        this.assignState({ turnCount: 0 });
+    }
+    async llmTurn(state) {
+        const result = await this.llmGenerateText.call({}, {
+            config: {
+                provider: 'claude',
+                system: this.render((0, node_path_1.join)(__dirname, 'templates', 'system.md')),
+                tools: ['weather_lookup', 'calculator'],
+            },
+        });
+        this.assignState({
+            turnCount: state.turnCount + 1,
+            llmResult: result.data,
+        });
+    }
+    async notifyOverBudget(_state) {
+        await this.documentStore.save(llm_provider_module_1.LlmMessageDocument, {
+            role: 'user',
+            text: `You have used your full turn budget of ${MAX_TURNS} tool-using turns and can no longer call tools. ` +
+                'Summarise what you found so far in plain text and answer based on that.',
+        });
+    }
+    async wrapUp(_state) {
+        await this.llmGenerateText.call({}, {
+            config: {
+                provider: 'claude',
+                system: this.render((0, node_path_1.join)(__dirname, 'templates', 'wrap-up.md')),
+                tools: [],
+            },
+        });
+    }
+    async executeToolCalls(state) {
+        const result = await this.llmDelegateToolCalls.call({
+            message: state.llmResult.message,
+            callback: { transition: 'toolResultReceived' },
+        });
+        this.assignState({ delegateResult: result.data });
+    }
+    async toolResultReceived(state, input) {
+        const result = await this.llmUpdateToolResult.call({
+            delegateResult: state.delegateResult,
+            completedTool: input,
+        });
+        this.assignState({ delegateResult: result.data });
+    }
+    toolsComplete(_state) { }
+    respond(_state) { }
+    hasBudget(state) {
+        return state.turnCount < MAX_TURNS;
+    }
+    isOverBudget(state) {
+        return state.turnCount >= MAX_TURNS;
+    }
+    hasToolCalls(state) {
+        return state.llmResult?.message.stopReason === 'tool_use';
+    }
+    allToolsComplete(state) {
+        return !!state.delegateResult?.allCompleted;
+    }
+    isEndTurn(state) {
+        return state.llmResult?.message.stopReason === 'end_turn';
+    }
+};
+exports.CustomAgentExampleWorkflow = CustomAgentExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'ready' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CustomAgentExampleWorkflow.prototype, "setup", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'ready', to: 'prompt_executed', priority: 10 }),
+    (0, common_1.Guard)('hasBudget'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CustomAgentExampleWorkflow.prototype, "llmTurn", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'ready', to: 'over_budget' }),
+    (0, common_1.Guard)('isOverBudget'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CustomAgentExampleWorkflow.prototype, "notifyOverBudget", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'over_budget', to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CustomAgentExampleWorkflow.prototype, "wrapUp", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 }),
+    (0, common_1.Guard)('hasToolCalls'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CustomAgentExampleWorkflow.prototype, "executeToolCalls", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'awaiting_tools', to: 'awaiting_tools', wait: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], CustomAgentExampleWorkflow.prototype, "toolResultReceived", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'awaiting_tools', to: 'ready' }),
+    (0, common_1.Guard)('allToolsComplete'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], CustomAgentExampleWorkflow.prototype, "toolsComplete", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'prompt_executed', to: 'end' }),
+    (0, common_1.Guard)('isEndTurn'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], CustomAgentExampleWorkflow.prototype, "respond", null);
+exports.CustomAgentExampleWorkflow = CustomAgentExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Agent - Custom Agent Example',
+        description: 'A from-scratch agent loop with a deterministic turn budget. After N tool-using turns the workflow forces a wrap-up LLM call with a different system prompt and no tools — illustrating a control-flow shape the generic AgentWorkflow cannot express.',
+    }),
+    __metadata("design:paramtypes", [llm_provider_module_1.LlmGenerateTextTool,
+        llm_provider_module_1.LlmDelegateToolCallsTool,
+        llm_provider_module_1.LlmUpdateToolResultTool])
+], CustomAgentExampleWorkflow);
+//# sourceMappingURL=custom-agent-example.workflow.js.map

package/dist/workflows/custom-agent/custom-agent-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-agent-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/custom-agent/custom-agent-example.workflow.ts"],"names":[],"mappings":"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"}

package/dist/workflows/custom-agent/templates/system.md

@@ -0,0 +1,14 @@
+You are a helpful assistant searching for a city that matches the user's criteria.
+
+Available tools:
+
+- `weather_lookup` — look up the current weather for a city
+- `calculator` — perform a basic arithmetic calculation
+
+How to work:
+
+- Look up exactly ONE city per turn — never call `weather_lookup` for multiple cities in parallel.
+- After each lookup, reason about the result before deciding whether to keep searching.
+- Stop calling tools as soon as you have enough information to answer.
+
+When you are done, answer in plain text without calling any more tools.

package/dist/workflows/custom-agent/templates/wrap-up.md

@@ -0,0 +1,3 @@
+You have reached your turn budget and can no longer call tools.
+
+Summarize what you have found so far for the user in plain text. If you did not finish gathering every data point, acknowledge that and answer based on what you have. Do not call any tools.

package/dist/workflows/mcp-linear/mcp-linear-example.workflow.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { ChatAgentWorkflow } from '@loopstack/agent';
+import { BaseWorkflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { McpCallTool, McpListToolsTool } from '@loopstack/mcp-module';
+declare const McpLinearExampleArgsSchema: z.ZodObject<{
+    initialMessage: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+type McpLinearExampleArgs = z.infer<typeof McpLinearExampleArgsSchema>;
+export declare class McpLinearExampleWorkflow extends BaseWorkflow<McpLinearExampleArgs> {
+    private readonly chatAgentWorkflow;
+    private readonly mcpListTools;
+    private readonly mcpCallTool;
+    constructor(chatAgentWorkflow: ChatAgentWorkflow, mcpListTools: McpListToolsTool, mcpCallTool: McpCallTool);
+    startChat(state: Record<string, unknown>, ctx: RunContext<McpLinearExampleArgs>): Promise<void>;
+}
+export {};
+//# sourceMappingURL=mcp-linear-example.workflow.d.ts.map

package/dist/workflows/mcp-linear/mcp-linear-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-linear-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/mcp-linear/mcp-linear-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAwB,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAItE,QAAA,MAAM,0BAA0B;;iBAQ9B,CAAC;AAEH,KAAK,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAEvE,qBAKa,wBAAyB,SAAQ,YAAY,CAAC,oBAAoB,CAAC;IAE5E,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAFX,iBAAiB,EAAE,iBAAiB,EACpC,YAAY,EAAE,gBAAgB,EAC9B,WAAW,EAAE,WAAW;IAMrC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,oBAAoB,CAAC;CAgBtF"}

package/dist/workflows/mcp-linear/mcp-linear-example.workflow.js

@@ -0,0 +1,65 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpLinearExampleWorkflow = void 0;
+const zod_1 = require("zod");
+const agent_1 = require("@loopstack/agent");
+const common_1 = require("@loopstack/common");
+const mcp_module_1 = require("@loopstack/mcp-module");
+const LINEAR_MCP_URL = 'https://mcp.linear.app/mcp';
+const McpLinearExampleArgsSchema = zod_1.z.object({
+    initialMessage: zod_1.z
+        .string()
+        .optional()
+        .default('List the available Linear MCP tools, then fetch my active issues and summarize the top 5 by priority with assignee and status.')
+        .describe('Initial message shown to the agent.'),
+});
+let McpLinearExampleWorkflow = class McpLinearExampleWorkflow extends common_1.BaseWorkflow {
+    chatAgentWorkflow;
+    mcpListTools;
+    mcpCallTool;
+    constructor(chatAgentWorkflow, mcpListTools, mcpCallTool) {
+        super();
+        this.chatAgentWorkflow = chatAgentWorkflow;
+        this.mcpListTools = mcpListTools;
+        this.mcpCallTool = mcpCallTool;
+    }
+    async startChat(state, ctx) {
+        const systemPrompt = [
+            `You are a Linear assistant connected via MCP at ${LINEAR_MCP_URL} (transport: streamableHttp).`,
+            'Use `mcpListTools` to discover the available Linear tools, then `mcpCallTool` to invoke them.',
+            `Always pass serverUrl="${LINEAR_MCP_URL}" and transport="streamableHttp".`,
+        ].join('\n');
+        await this.chatAgentWorkflow.run({
+            system: systemPrompt,
+            tools: ['mcp_list_tools', 'mcp_call'],
+            userMessage: ctx.args.initialMessage,
+        }, { show: 'inline', label: 'Linear Agent Chat' });
+    }
+};
+exports.McpLinearExampleWorkflow = McpLinearExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'chatting' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], McpLinearExampleWorkflow.prototype, "startChat", null);
+exports.McpLinearExampleWorkflow = McpLinearExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Agent - MCP Linear Example',
+        description: "Chat agent connected to Linear's hosted MCP server. Demonstrates MCP tool integration.",
+        schema: McpLinearExampleArgsSchema,
+    }),
+    __metadata("design:paramtypes", [agent_1.ChatAgentWorkflow,
+        mcp_module_1.McpListToolsTool,
+        mcp_module_1.McpCallTool])
+], McpLinearExampleWorkflow);
+//# sourceMappingURL=mcp-linear-example.workflow.js.map

package/dist/workflows/mcp-linear/mcp-linear-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-linear-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/mcp-linear/mcp-linear-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,4CAAqD;AACrD,8CAAuE;AAEvE,sDAAsE;AAEtE,MAAM,cAAc,GAAG,4BAA4B,CAAC;AAEpD,MAAM,0BAA0B,GAAG,OAAC,CAAC,MAAM,CAAC;IAC1C,cAAc,EAAE,OAAC;SACd,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CACN,gIAAgI,CACjI;SACA,QAAQ,CAAC,qCAAqC,CAAC;CACnD,CAAC,CAAC;AASI,IAAM,wBAAwB,GAA9B,MAAM,wBAAyB,SAAQ,qBAAkC;IAE3D;IACA;IACA;IAHnB,YACmB,iBAAoC,EACpC,YAA8B,EAC9B,WAAwB;QAEzC,KAAK,EAAE,CAAC;QAJS,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,iBAAY,GAAZ,YAAY,CAAkB;QAC9B,gBAAW,GAAX,WAAW,CAAa;IAG3C,CAAC;IAGK,AAAN,KAAK,CAAC,SAAS,CAAC,KAA8B,EAAE,GAAqC;QACnF,MAAM,YAAY,GAAG;YACnB,mDAAmD,cAAc,+BAA+B;YAChG,+FAA+F;YAC/F,0BAA0B,cAAc,mCAAmC;SAC5E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAC9B;YACE,MAAM,EAAE,YAAY;YACpB,KAAK,EAAE,CAAC,gBAAgB,EAAE,UAAU,CAAC;YACrC,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,cAAc;SACrC,EACD,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAC/C,CAAC;IACJ,CAAC;CACF,CAAA;AA1BY,4DAAwB;AAU7B;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC;;;;yDAgB9B;mCAzBU,wBAAwB;IALpC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,4BAA4B;QACnC,WAAW,EAAE,wFAAwF;QACrG,MAAM,EAAE,0BAA0B;KACnC,CAAC;qCAGsC,yBAAiB;QACtB,6BAAgB;QACjB,wBAAW;GAJhC,wBAAwB,CA0BpC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@loopstack/agent-examples",
+  "displayName": "Loopstack Agent Examples",
+  "description": "Workflow examples for LLM agents in Loopstack — basic AgentWorkflow, code-exploration agent, MCP-connected agent, and a from-scratch custom agent loop with a deterministic turn budget.",
+  "keywords": [
+    "loopstack",
+    "example",
+    "agent",
+    "llm",
+    "claude",
+    "mcp",
+    "workflow"
+  ],
+  "version": "0.1.1",
+  "license": "MIT",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@loopstack/agent": "*",
+    "@loopstack/claude-module": "*",
+    "@loopstack/code-agent": "*",
+    "@loopstack/common": "*",
+    "@loopstack/llm-provider-module": "*",
+    "@loopstack/mcp-module": "*",
+    "@loopstack/remote-client": "*",
+    "@nestjs/common": "^11.1.19",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.6",
+    "@swc/core": "^1.15.33",
+    "unplugin-swc": "^1.5.9"
+  }
+}

package/src/agent-examples.module.ts

@@ -0,0 +1,40 @@
+import { Module } from '@nestjs/common';
+import { AgentModule } from '@loopstack/agent';
+import { ClaudeModule } from '@loopstack/claude-module';
+import { CodeAgentModule } from '@loopstack/code-agent';
+import { StudioApp } from '@loopstack/common';
+import { McpModule } from '@loopstack/mcp-module';
+import { RemoteClientModule } from '@loopstack/remote-client';
+import { CalculatorTool } from './tools/calculator.tool';
+import { WeatherLookupTool } from './tools/weather-lookup.tool';
+import { AgentExampleWorkflow } from './workflows/agent/agent-example.workflow';
+import { CodeAgentExampleWorkflow } from './workflows/code-agent/code-agent-example.workflow';
+import { CustomAgentExampleWorkflow } from './workflows/custom-agent/custom-agent-example.workflow';
+import { McpLinearExampleWorkflow } from './workflows/mcp-linear/mcp-linear-example.workflow';
+
+const WORKFLOWS = [
+  AgentExampleWorkflow,
+  CodeAgentExampleWorkflow,
+  McpLinearExampleWorkflow,
+  CustomAgentExampleWorkflow,
+];
+
+@StudioApp({
+  title: 'Agent Examples',
+  workflows: WORKFLOWS,
+})
+@Module({
+  imports: [
+    AgentModule,
+    CodeAgentModule,
+    ClaudeModule,
+    McpModule.forRoot({
+      allowedHosts: ['mcp.linear.app'],
+      hostHeaderEnv: { 'mcp.linear.app': { Authorization: 'LINEAR_MCP_TOKEN' } },
+    }),
+    RemoteClientModule.forFeature({ slots: [{ id: 'sandbox', type: 'sandbox', title: 'Sandbox' }] }),
+  ],
+  providers: [CalculatorTool, WeatherLookupTool, ...WORKFLOWS],
+  exports: WORKFLOWS,
+})
+export class AgentExamplesModule {}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './agent-examples.module';
+export * from './workflows/agent/agent-example.workflow';
+export * from './workflows/code-agent/code-agent-example.workflow';
+export * from './workflows/mcp-linear/mcp-linear-example.workflow';
+export * from './workflows/custom-agent/custom-agent-example.workflow';

package/src/tools/calculator.tool.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+
+export type CalculatorResult = string;
+
+@Tool({
+  name: 'calculator',
+  description: 'Perform a basic arithmetic calculation. Supports add, subtract, multiply, divide.',
+  schema: z.object({
+    operation: z.enum(['add', 'subtract', 'multiply', 'divide']).describe('The arithmetic operation.'),
+    a: z.number().describe('First operand.'),
+    b: z.number().describe('Second operand.'),
+  }),
+})
+export class CalculatorTool extends BaseTool<{ operation: string; a: number; b: number }, object, CalculatorResult> {
+  protected async handle(
+    args: { operation: string; a: number; b: number },
+    _ctx: RunContext,
+  ): Promise<ToolEnvelope<CalculatorResult>> {
+    let result: number;
+
+    switch (args.operation) {
+      case 'add':
+        result = args.a + args.b;
+        break;
+      case 'subtract':
+        result = args.a - args.b;
+        break;
+      case 'multiply':
+        result = args.a * args.b;
+        break;
+      case 'divide':
+        if (args.b === 0) {
+          return { data: 'Error: Division by zero', error: 'Cannot divide by zero' };
+        }
+        result = args.a / args.b;
+        break;
+      default:
+        return { data: `Unknown operation: ${args.operation}`, error: 'Unsupported operation' };
+    }
+
+    return {
+      data: `${args.a} ${args.operation} ${args.b} = ${result}`,
+    };
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,2 @@
+export * from './weather-lookup.tool';
+export * from './calculator.tool';

package/src/tools/weather-lookup.tool.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+
+export type WeatherLookupResult = string;
+
+@Tool({
+  name: 'weather_lookup',
+  description: 'Look up the current weather for a given city. Returns a simulated forecast.',
+  schema: z.object({
+    city: z.string().describe('The city name to look up weather for.'),
+  }),
+})
+export class WeatherLookupTool extends BaseTool<{ city: string }, object, WeatherLookupResult> {
+  protected async handle(args: { city: string }): Promise<ToolEnvelope<WeatherLookupResult>> {
+    // Simulated weather data for demonstration purposes
+    const forecasts: Record<string, string> = {
+      london: '14°C, cloudy with light rain',
+      tokyo: '22°C, sunny with clear skies',
+      'new york': '18°C, partly cloudy',
+    };
+
+    const key = args.city.toLowerCase();
+    const weather = forecasts[key] ?? `21°C, pleasant conditions`;
+
+    return Promise.resolve({
+      data: `Weather in ${args.city}: ${weather}`,
+    });
+  }
+}

package/src/workflows/agent/agent-example.workflow.ts

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { type AgentResult, AgentResultSchema, AgentWorkflow } from '@loopstack/agent';
+import { BaseWorkflow, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { LlmMessageDocument } from '@loopstack/llm-provider-module';
+
+@Workflow({
+  title: 'Agent - Basic Agent Example',
+  description:
+    'Launches a generic AgentWorkflow as a sub-workflow with weather and calculator tools. Recommended starting point.',
+})
+export class AgentExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly agentWorkflow: AgentWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'running' })
+  async start() {
+    await this.agentWorkflow.run(
+      {
+        system: this.render(join(__dirname, 'templates', 'system.md')),
+        tools: ['weather_lookup', 'calculator'],
+        userMessage: "What's the weather in Tokyo? Also, what is 42 * 17?",
+      },
+      { callback: { transition: 'agentComplete' }, show: 'inline', label: 'Subagent' },
+    );
+  }
+
+  @Transition({
+    from: 'running',
+    to: 'end',
+    wait: true,
+    schema: AgentResultSchema,
+  })
+  async agentComplete(_state: Record<string, unknown>, input: TransitionInput<AgentResult>) {
+    await this.documentStore.save(LlmMessageDocument, {
+      role: 'assistant',
+      text: input.data.response,
+    });
+  }
+}

package/src/workflows/agent/templates/system.md

@@ -0,0 +1,4 @@
+You are a helpful assistant with access to a weather lookup tool and a calculator.
+When the user asks about weather, use the weatherLookup tool.
+When the user asks for calculations, use the calculator tool.
+Provide a concise, helpful response summarizing the results.

package/src/workflows/code-agent/code-agent-example.workflow.ts

@@ -0,0 +1,56 @@
+import { type AgentResult, AgentResultSchema, AgentWorkflow } from '@loopstack/agent';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { EnvironmentService } from '@loopstack/remote-client';
+
+const EXPLORE_INSTRUCTIONS = `Find the entry-point module of this project and list the
+top-level providers it registers. Return a short bulleted summary.`;
+
+/**
+ * Code-exploration agent powered by `AgentWorkflow` with `glob`, `grep`, and `read`
+ * tools. These tools execute on a remote agent, so the workspace must have a
+ * `sandbox` environment connected and the remote agent must be reachable.
+ *
+ * Setup (see `agent-examples/README.md` → Code Agent for the full snippet):
+ */
+@Workflow({
+  title: 'Agent - Code Agent Example',
+  description: 'Launches AgentWorkflow as a codebase-exploration agent with glob, grep, and read tools.',
+})
+export class CodeAgentExampleWorkflow extends BaseWorkflow {
+  constructor(
+    private readonly agentWorkflow: AgentWorkflow,
+    private readonly environments: EnvironmentService,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'verified' })
+  async verifyEnvironment(_state: Record<string, unknown>) {
+    await this.environments.assertReachable('sandbox');
+  }
+
+  @Transition({ from: 'verified', to: 'exploring' })
+  async startExploration(_state: Record<string, unknown>) {
+    await this.agentWorkflow.run(
+      {
+        system: 'You are a codebase exploration agent. Search and read source code to answer the question thoroughly.',
+        tools: ['glob', 'grep', 'read'],
+        userMessage: EXPLORE_INSTRUCTIONS,
+      },
+      { callback: { transition: 'exploreComplete' }, show: 'inline', label: 'Exploring codebase...' },
+    );
+  }
+
+  @Transition({
+    from: 'exploring',
+    to: 'end',
+    wait: true,
+    schema: AgentResultSchema,
+  })
+  async exploreComplete(_state: Record<string, unknown>, input: TransitionInput<AgentResult>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: input.data.response,
+    });
+  }
+}