Skip to content
Color theme

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, 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
>;