Agent Forge

​

Installation

npm install @lousho/build-ai-agent

​

Quickstart

npx lousho studio

npx lousho studio --port 5000       # pick a different port
npx lousho studio --host 0.0.0.0    # bind to all interfaces
npx lousho studio --prod            # force production mode (see below)
npx lousho studio --dev             # force dev mode (monorepo only)

​

Production vs. dev mode

• Production (the default once Agent Forge has been built): a single Express server serves both the REST/WebSocket API and the pre-built client (React app) as static files, on one port. This is what runs when you npm install the published package - there’s no separate Vite dev server and no TypeScript loader involved.
• Dev (falls back to this if the build hasn’t been run yet, i.e. inside a source checkout of this monorepo): the API server runs straight off its TypeScript source via tsx, alongside a real Vite dev server (with hot-module reload) that proxies API requests to it. Two processes, two ports internally, one command.

​

First-agent walkthrough

1. Create an agent. In the left rail’s “Agents” tab, click New, give it a name, and pick a starting template - Blank graph (a single LLM node using the built-in mock provider) is the fastest way to try things out without any API keys. Agent Forge creates the agent and opens it on the canvas.
2. Look at the graph. A blank agent is one llm node. Drag more nodes in from the left rail’s palette (Trigger, LLM step, Tool call, Approval gate, Response / output) and connect them by dragging between their handles. Click a node to edit its settings (prompt, provider/model, tools, breakpoints) in the Inspector on the right.
3. Run it. Click Run in the top bar. With the mock provider there’s nothing to configure - it returns deterministic canned output, which is exactly the point for trying the rest of the UI without needing a real LLM API key. The status pill in the top bar tracks the run (running → idle/error/awaiting approval).
4. Watch it in the debug console. Open the bottom drawer’s Logs tab for a live, filterable log feed of the run (trigger/llm/tool/ sandbox/checkpoint/approval events), or Trace for a span waterfall. Turn on Debug in the top bar (or set a breakpoint on a node in the Inspector) to pause the run at LLM/tool boundaries and step through it with the debug bar’s Step/Continue controls; expand “Live message array” there to inspect the in-flight message list. Output shows the full ExecutionResult (messages, tool calls, usage, steps) as a collapsible JSON tree once the run finishes or pauses.
5. Chat with it. The Chat tab is a separate conversational transport (POST /agents/:id/message, streamed back over the same WebSocket as everything else) - send it a message and it replies in the thread, independent of the graph “Run” button above. Each agent keeps its own chat history (+ New chat starts a fresh session; old ones stay browsable).
6. Approve a paused tool call. Add a Tool call node, open it in the Inspector, and pick a tool - some tools (or an agent’s own policy) can require human approval before running. When a run or chat hits one, an inline approval card appears (in the top bar for a graph run, or as a message bubble in the Chat thread) showing the tool name and its arguments. Click Approve to let it proceed or Reject to abort that call; the run resumes automatically either way.

​

Hooks

1. Select an llm or tool node on the canvas (hooks only apply to these - they’re the two points AgentExecutor actually calls out to).
2. Open the Inspector’s Hooks section. Drag a Pre-hook or Post-hook entry from the left rail’s palette onto the node (or drop it directly in the Hooks section) to attach a new one; you’ll get a choice of starter templates (redact-pii, rate-limit, audit-log, inject-context) as an editable starting point.
3. Click the hook’s chip to select it, then edit its code in the CodeMirror editor. The code is the body of an async function invoked as hook(ctx) inside a sandboxed subprocess (server/hookSandbox.ts) - never in the browser or the API server process itself:
   • For a tool-call hook, ctx is { toolName, args, result?, error? }. A pre-hook can mutate ctx.args; a post-hook can inspect/mutate ctx.result/ctx.error. Return ctx.
   • For an LLM-generate hook, ctx is { messages, model }. Mutate/push onto ctx.messages and return ctx.
   • Throwing aborts the step - a rate-limit hook, for example, throws to block the tool call outright rather than letting it run.
4. Toggle the switch on a hook’s chip to enable/disable it without removing it, or use its x to remove it entirely. Only enabled hooks are compiled into the run.

const PII = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/gi;
for (const key of Object.keys(ctx.args || {})) {
  if (typeof ctx.args[key] === 'string') {
    ctx.args[key] = ctx.args[key].replace(PII, '[REDACTED]');
  }
}
return ctx;

​

Time travel

​

The History tab

1. Run the agent (Topbar Run, or a Chat message).
2. Open the bottom drawer’s History tab. It lists the run’s steps: step number, status, the model’s finish reason, the tool calls made, and the tokens and cost of the step’s model call when known.
3. Click Edit and replay from here on a step. Choose Append a user message and type one, or pick one of the step’s tool calls to edit its result (prefilled with the recorded result; text that parses as JSON is sent as JSON).
4. Click Fork and replay. The run is forked at that step with your edit and started as a new run, <id>.fork-<n>.
5. The fork opens next to the original as a side-by-side trajectory: each model turn of both runs (text, tool calls and results), the first turn where they differ highlighted as diverged, and the drift entries (tool order, arguments, step count, finish reason) listed below. It refreshes when the fork finishes.

​

Routes

curl localhost:4750/runs/weather/history
# {"runId":"weather","steps":[{"step":1,"status":"finished","finishReason":"stop","toolCalls":[],"tokens":...}]}

curl -X POST localhost:4750/runs/weather/fork -H 'content-type: application/json' \
  -d '{"fromStep":1,"patch":{"appendInput":"And in Celsius?"}}'
# {"runId":"weather.fork-1","fromStep":1,"status":{"status":"running",...}}

curl 'localhost:4750/runs/compare?a=weather&b=weather.fork-1'
# {"a":[...],"b":[...],"divergedAt":2,"drift":[{"field":"steps","committed":"1","current":"2"}]}

​

Settings, secrets and deploy wiring

​

Dev mode

git clone https://github.com/LinuxDevil/agent-sdk.git
cd agent-sdk
npm install
npx lousho studio --dev   # or just `npx lousho studio` before building

npm run build:studio   # builds apps/agent-forge/dist (client) and
                        # apps/agent-forge/dist-server (bundled server)
npx lousho studio       # now runs in production mode

​

E2E smoke test

npm run test:e2e:studio   # from the repo root, or apps/agent-forge/