What You Can Build
Agent harnesses with tool calling, context and message history
Stateful automations that chain tools, transform data, and route dynamically
Compose complex systems by spawning nested agents and workflows
Run code and access files in isolated sandboxed environments
Pause workflows for human review, input, or confirmation
...built directly into your NestJS backends.
How It Works
Workflows, Tools, Documents and Modules
@Workflow({ schema: TriageSchema })
export class TriageWorkflow extends BaseWorkflow {
// inject tools here
@Transition({ from: 'start', to: 'classified' })
async classify(state, ctx) {
const result = await this.llm.call({
outputSchema: ClassificationSchema,
prompt: ctx.args.ticket,
});
return { ...state, classification: result.data };
}
@Transition({ from: 'classified', to: 'end' })
async notifyTeam(state) {
await this.notify.call(state.classification);
}
}Workflows
Workflows are TypeScript state machines with explicit states and transitions. Inject tools, call LLMs, save documents — each step is checkpointed. If something fails, resume from exactly where you left off.
Learn moreRun and Interact in the browser
Use the built-in ReactJS frontend for running, debugging and organizing automations.
Key Benefits
Drop an LLM call into any point in a deterministic workflow, or nest agents inside structured pipelines. One system, not two bolted together.
Approvals, forms, confirmations, and clarifications ship as framework primitives. Pause for human input for hours or days and resume cleanly.
Extend it like any NestJS app — add your own modules, providers, and entities. No vendor lock-in, no external execution engine. Free and open source under the MIT license.
Every state transition, tool call, and LLM decision is recorded. State is checkpointed so failures resume cleanly. Explicit state machines make workflows auditable and easy to reason about.
See It In Action
Agents With Full Control
Use a ready made agent or create your own flow. Same system, just the right level of abstraction.
Call an Agent
await this.agent.run(
{
system: 'Review the codebase and write a summary.',
tools: ['read', 'glob', 'grep'],
userMessage: 'Focus on the auth module.',
},
{ callback: { transition: 'agentDone' } },
);Build Your Own
@Transition({ from: 'ready', to: 'tools_executed' })
async llmTurn(state) {
const result = await this.llmGenerateText.call({
system: 'Review the codebase and write a summary.',
tools: ['read', 'glob', 'grep'],
});
return { ...state, llmResult: result.data };
}
@Transition({ from: 'tools_executed', to: 'ready' })
@Guard('hasToolCalls')
async loop(state) { return state; }
// agent done
@Transition({ from: 'tools_executed', to: 'end' })
async notify(state) {
await this.notify.call(state.llmResult);
}Tool calling, error recovery, and cancellation built in. Need custom exit logic, setup phases, or human interaction? Copy the agent and make it yours.
Nested Agents and -Workflows
Let agents launch sub-agents: Just wrap them in tools.
1. Define a workflow
@Workflow({ schema: TestRunnerSchema })
export class TestRunnerWorkflow extends BaseWorkflow {
// runs tests, returns results
}2. Wrap it as a tool
@Tool({ name: 'run_tests', schema: RunTestsSchema })
export class RunTestsTool extends BaseTool {
// inject workflow via constructor
async handle(args, ctx, options) {
const result = await this.testRunner.run(
args, { callback: options?.callback },
);
return { pending: { workflowId: result.workflowId } };
}
}3. Let the agent use it
await this.llmGenerateText.call({
system: 'You are a build agent.',
tools: ['read', 'write', 'run_tests'],
});The LLM decides when to launch sub-workflows. Each one runs in the background and reports back. Nest workflows as you need.
Built-In Error Recovery
Auto-retry, timeout, and custom error states.
Auto-Retry
@Transition({
from: 'fetching',
to: 'done',
retry: 3,
})
async fetchData(state) {
await this.http.call({ url });
return state;
}Retries 3 times with exponential backoff. State rolls back between attempts.
Timeout
@Transition({
from: 'analyzing',
to: 'done',
timeout: 5000,
})
async analyze(state) {
await this.analyzer.call({ data });
return state;
}Kills the transition after 5s. Combine with retry to auto-retry on timeout.
Error States
@Transition({
from: 'deploying',
to: 'deployed',
retry: { place: 'deploy_failed' },
})
async deploy(state) {
await this.deployer.call({});
return state;
}Routes to a custom error state with recovery transitions.
Documents and state roll back automatically on failure. Every error is recorded as an audit trail. Manual retry is always available as a fallback.
Human-in-the-Loop
Pause for human input. Resume hours or days later. State is always preserved.
Ask a Question
@Transition({ from: 'start', to: 'waiting' })
async showQuestion(state, ctx) {
await this.documentStore.save(
AskUserDocument,
{ question: ctx.args.question },
);
return state;
}
// pauses until user responds
@Transition({ from: 'waiting', to: 'end', wait: true })
async userAnswered(state, payload) {
return { answer: payload.answer };
}Render the UI
widget: choices
options:
transition: userAnsweredDocuments define the data, YAML configures how it renders. The workflow sleeps until the user responds — no polling, no timeouts, no lost state.
Configurable UI
Documents define your data. A YAML config controls how they render - choices, forms, buttons, markdown. No frontend code needed.
The workflow renders the UI, pauses execution, the user responds, and the workflow continues.
widget: choices
options:
transition: userAnswered
Get Started
Use in any NestJS app. Docker environment included.
npm install @loopstack/loopstack-moduleSupported by:
