API: @loopstack/agent
Classes
AgentFinishTool
Tool that signals the agent has completed its task and returns the final result.
The LLM calls this to end the loop, passing the final result as a structured object
or string. Returns an AgentFinishResult the agent workflow uses to exit.
import { AgentFinishTool } from '@loopstack/agent';Provided by: AgentModule
export class AgentFinishTool extends BaseTool<AgentFinishInput, object, AgentFinishResult> { protected handle(args: AgentFinishInput): Promise<ToolEnvelope<AgentFinishResult>>;}AgentModule
NestJS module that provides the agent workflows (AgentWorkflow,
ChatAgentWorkflow) and the AgentFinishTool.
Registration:
AgentModule(bare import) — registers the agent workflows; the LLM provider/model defaults come from whateverLlmProviderModuleis configured app-wide.AgentModule.forFeature({ llm })— same workflows, but with a feature-scopedLlmProviderModule.forFeature(llm)so this scope uses its own provider/model defaults.
Requires: LlmProviderModule plus a registered provider module (e.g.
ClaudeModule / OpenAiModule) available in the app — the agent loop runs its
turns through that provider.
import { AgentModule } from '@loopstack/agent';export class AgentModule { static forFeature(config?: { llm?: LlmModuleConfig }): DynamicModule;}AgentWorkflow
Workflow that runs a generic LLM agent loop: prompt the LLM, delegate any tool
calls, feed their results back, and repeat until the model returns end_turn.
Args (per run()): system, tools, userMessage, and optional context, provider and model.
Tool names in tools are resolved by their @Tool({ name }) value from the app-wide tool registry.
On completion it publishes an AgentResult with the final assistant response.
import { AgentWorkflow } from '@loopstack/agent';Provided by: AgentModule
export class AgentWorkflow extends BaseWorkflow<AgentArgs> { constructor( llmGenerateText: LlmGenerateTextTool, llmDelegateToolCalls: LlmDelegateToolCallsTool, llmUpdateToolResult: LlmUpdateToolResultTool, orchestrator: WorkflowOrchestrator, ); setup(state: AgentState, ctx: RunContext<AgentArgs>): Promise<void>; llmTurn(state: AgentState): Promise<void>; executeToolCalls(state: AgentState): Promise<void>; toolResultReceived(state: AgentState, input: TransitionInput): Promise<void>; toolsComplete(_state: AgentState): void; cancelPendingTools(state: AgentState, ctx: RunContext): Promise<void>; respond(state: AgentState): void;}ChatAgentWorkflow
Workflow that runs an interactive LLM agent loop with user chat between turns.
Behaves like AgentWorkflow , but instead of exiting on end_turn it
transitions to waiting_for_user and resumes on the next user message. When
the taskMode arg is set, the agent_finish tool is added and the LLM
calling it ends the workflow with that tool’s result.
import { ChatAgentWorkflow } from '@loopstack/agent';Provided by: AgentModule
export class ChatAgentWorkflow extends BaseWorkflow<ChatAgentArgs> { constructor( llmGenerateText: LlmGenerateTextTool, llmDelegateToolCalls: LlmDelegateToolCallsTool, llmUpdateToolResult: LlmUpdateToolResultTool, agentFinish: AgentFinishTool, orchestrator: WorkflowOrchestrator, ); setup(state: ChatAgentState, ctx: RunContext<ChatAgentArgs>): Promise<void>; llmTurn(state: ChatAgentState): Promise<void>; executeToolCalls(state: ChatAgentState): Promise<void>; toolResultReceived(state: ChatAgentState, payload: unknown): Promise<void>; finished(state: ChatAgentState): void; toolsComplete(_state: ChatAgentState): void; cancelPendingTools(state: ChatAgentState, ctx: RunContext): Promise<void>; respond(_state: ChatAgentState): void; userMessage(state: ChatAgentState, input: TransitionInput<string>): Promise<void>;}Type Aliases
AgentArgs
Args for AgentWorkflow (passed to run()).
Holds system, tools, userMessage, and optional context, provider and model.
import { AgentArgs } from '@loopstack/agent';export type AgentArgs = z.infer<typeof AgentArgsSchema>;AgentFinishResult
Result returned by AgentFinishTool — a sentinel marking agent completion with
the final result.
import { AgentFinishResult } from '@loopstack/agent';export type AgentFinishResult = { __agentFinish: true; result: unknown;};AgentResult
Result returned by AgentWorkflow, inferred from AgentResultSchema.
Holds the final assistant response text.
import { AgentResult } from '@loopstack/agent';export type AgentResult = z.infer<typeof AgentResultSchema>;ChatAgentArgs
Args for ChatAgentWorkflow (passed to run()).
Holds system, tools, userMessage, and optional context, taskMode, provider and model.
import { ChatAgentArgs } from '@loopstack/agent';export type ChatAgentArgs = z.infer<typeof ChatAgentArgsSchema>;Variables
AgentArgsSchema
Zod schema for AgentWorkflow args (what callers pass to run()).
import { AgentArgsSchema } from '@loopstack/agent';AgentArgsSchema: z.ZodObject< { system: z.ZodString; tools: z.ZodArray<z.ZodString>; userMessage: z.ZodString; context: z.ZodOptional<z.ZodString>; provider: z.ZodOptional<z.ZodString>; model: z.ZodOptional<z.ZodString>; }, z.core.$strip>;AgentFinishResultSchema
Zod schema for AgentFinishResult.
import { AgentFinishResultSchema } from '@loopstack/agent';AgentFinishResultSchema: z.ZodObject< { __agentFinish: z.ZodLiteral<true>; result: z.ZodUnknown; }, z.core.$strict>;AgentResultSchema
Zod schema for the result published by AgentWorkflow.
Validates a single response string holding the final assistant message.
Reusable as the schema: on a parent’s callback wait-transition.
import { AgentResultSchema } from '@loopstack/agent';AgentResultSchema: z.ZodObject< { response: z.ZodString; }, z.core.$strip>;ChatAgentArgsSchema
Zod schema for ChatAgentWorkflow args (what callers pass to run()).
import { ChatAgentArgsSchema } from '@loopstack/agent';ChatAgentArgsSchema: z.ZodObject< { system: z.ZodString; tools: z.ZodArray<z.ZodString>; userMessage: z.ZodString; context: z.ZodOptional<z.ZodString>; taskMode: z.ZodOptional<z.ZodBoolean>; provider: z.ZodOptional<z.ZodString>; model: z.ZodOptional<z.ZodString>; }, z.core.$strip>;