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
Apps, Workflows, Tools and Documents
@App()
export class DefaultApp {
@InjectWorkflow() triage: TriageWorkflow;
@InjectWorkflow() agent: AgentWorkflow;
@InjectTool() read: ReadTool;
@InjectTool() write: WriteTool;
@InjectTool() glob: GlobTool;
}Apps
An app is the top-level container for your application. It declares which workflows users can run and which tools are available. Tools can be registered on the app or workflow level.
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: 'You are a code review agent.',
tools: ['read', 'glob', 'grep'],
userMessage: 'Review the auth module.',
},
{ callback: { transition: 'agentDone' } },
);Build Your Own
@Transition({ from: 'ready', to: 'prompt_executed' })
async llmTurn() {
const result = await this.llmGenerateText.call({
system: 'You are a code review agent.',
tools: ['read', 'glob', 'grep'],
});
this.llmResult = result.data;
}
@Transition({ from: 'prompt_executed', to: 'awaiting_tools' })
@Guard('hasToolCalls')
async executeTools() {
this.result = await this.delegate.call({
message: this.llmResult,
});
}
@Transition({ from: 'awaiting_tools', to: 'ready' })
@Guard('allToolsComplete')
async loop() {}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: z.object({ directory: z.string() }) })
export class TestRunnerWorkflow extends BaseWorkflow {
// runs tests, returns results
}2. Wrap it as a tool
@Tool({ schema: z.object({ directory: z.string() }) })
export class RunTestsTask extends BaseTool {
@InjectWorkflow() testRunner: TestRunnerWorkflow;
async call(args, 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', 'runTests'],
});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() {
await this.http.call({ url });
}Retries 3 times with exponential backoff. State rolls back between attempts.
Timeout
@Transition({
from: 'analyzing',
to: 'done',
timeout: 5000,
})
async analyze() {
await this.analyzer.call({ data });
}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() {
await this.deployer.call({});
}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: 'planning', to: 'asking' })
async askUser() {
await this.askUser.run(
{
question: 'Which database?',
options: ['Postgres', 'MySQL', 'SQLite'],
},
{ callback: { transition: 'userAnswered' } },
);
}
// pauses until user answers
@Transition({ from: 'asking', to: 'answered', wait: true })
async userAnswered(payload) {
this.selectedDb = payload.data.answer;
}Render the UI
type: document
ui:
widgets:
- 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.
type: document
ui:
widgets:
- widget: choices
options:
transition: userAnswered
Get Started
Use in any NestJS app. Docker environment included.
npm install @loopstack/loopstack-moduleSupported by:
