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 whatever LlmProviderModule is configured app-wide.
AgentModule.forFeature({ llm }) — same workflows, but with a feature-scoped LlmProviderModule.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. Tools are resolved from the current workflow first, then from the workspace. 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.


import { AgentArgs } from '@loopstack/agent';


export type AgentArgs = z.infer<typeof AgentArgsSchema>;

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, optional context, and optional taskMode.


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>;
}, z.core.$strip>

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>;
}, z.core.$strip>