denchhq App Agent Builder
This skill covers building apps that interact with the AI agent. For core app structure and manifest basics, see the parent app-builder skill (app-builder/SKILL.md).
Chat API (agent permission required)
Creating Sessions
// Create a new chat session
const { sessionId } = await dench.chat.createSession("My Analysis Session");
// List existing sessions
const sessions = await dench.chat.getSessions({ limit: 20 });
// Returns array of { id, title, createdAt, ... }
Sending Messages with Streaming
const result = await dench.chat.send(sessionId, "Analyze the people table and summarize trends", {
onEvent(event) {
switch (event.type) {
case "text-delta":
appendToChat(event.data);
break;
case "reasoning-delta":
updateThinking(event.data);
break;
case "tool-input-start":
showToolCall(event.name, event.args);
break;
case "tool-output-available":
showToolResult(event.result);
break;
}
},
});
// result contains the full accumulated response: { text, toolCalls, reasoning }
Chat History & Control
// Get message history for a session
const messages = await dench.chat.getHistory(sessionId);
// Returns array of { role, content, toolCalls?, ... }
// Check if a session has an active run
const isActive = await dench.chat.isActive(sessionId);
// Abort an active run
await dench.chat.abort(sessionId);
Simple Agent Message (fire-and-forget)
// Send a one-off message to the agent (no streaming, no session management)
await dench.agent.send("Remind me to check the reports tomorrow at 9am");
App-as-Tool (agent permission required)
Apps can expose themselves as tools that the agent can invoke. Declare tools in the manifest:
name: "Chart Analyzer"
permissions:
- agent
tools:
- name: "analyze-chart"
description: "Generates a visual chart analysis from structured data"
inputSchema:
type: object
properties:
data:
type: array
description: "Array of data points"
chartType:
type: string
enum: ["bar", "line", "pie", "scatter"]
required: ["data", "chartType"]
Register tool handlers in the app:
dench.tool.register("analyze-chart", async (input) => {
const { data, chartType } = input;
// Process the data and generate the chart
const chart = renderChart(data, chartType);
const analysis = analyzeData(data);
// Return result to the agent
return {
analysis: analysis,
chartImageUrl: chart.toDataURL(),
summary: `Generated ${chartType} chart with ${data.length} data points`,
};
});
When the agent invokes the tool, the app receives the input, processes it, and returns the result. The app must be open (active tab) for tool invocation to work.
Agent Memory Access (agent permission required)
// Read the agent's memory (MEMORY.md + daily logs)
const memory = await dench.memory.get();
// Returns { memory: "...", dailyLogs: [...] }
Gateway WebSocket Protocol (Advanced)
For advanced apps that want to build their own chat UI or need direct Gateway access, here's the WebSocket protocol:
Connection
const ws = new WebSocket("ws://127.0.0.1:18789");
// Port is configurable via gateway.port in ~/.openclaw-dench/openclaw.json
Frame Types
// Request (client -> gateway)
{ type: "req", id: "uuid", method: "agent", params: { ... } }
// Response (gateway -> client)
{ type: "res", id: "uuid", ok: true, payload: { ... } }
// Event (gateway -> client)
{ type: "event", event: "agent", seq: 1, payload: { ... } }
Connection Handshake
ws.onopen = () => {
ws.send(
JSON.stringify({
type: "req",
id: crypto.randomUUID(),
method: "connect",
params: {
minProtocol: 3,
maxProtocol: 3,
client: { id: "my-app", version: "1.0", platform: "web", mode: "backend" },
role: "user",
scopes: ["agent", "chat"],
caps: ["tool-events"],
},
}),
);
};
Sending Messages
// Start an agent run
ws.send(
JSON.stringify({
type: "req",
id: crypto.randomUUID(),
method: "agent",
params: {
message: "Hello, analyze this data",
sessionKey: "agent:main:web:my-session-id",
channel: "webchat",
lane: "web",
},
}),
);
// Abort a run
ws.send(
JSON.stringify({
type: "req",
id: crypto.randomUUID(),
method: "chat.abort",
params: { sessionKey: "agent:main:web:my-session-id" },
}),
);
Agent Events
ws.onmessage = (e) => {
const frame = JSON.parse(e.data);
if (frame.type !== "event" || frame.event !== "agent") return;
const { stream, data } = frame.payload;
switch (stream) {
case "lifecycle":
// data.phase: "start" | "end" | "error"
break;
case "thinking":
// data.delta: incremental reasoning text
break;
case "assistant":
// data.delta: incremental response text
// data.text: full text (on completion)
// data.stopReason: "end_turn" | "tool_use" | etc.
break;
case "tool":
// data.phase: "start" | "update" | "result"
// data.name, data.args, data.result
break;
}
};
NOTE: For most apps, the bridge chat API (dench.chat.*) is much simpler than direct WebSocket usage. Use the Gateway WS only when you need full control over the connection.
Patterns
Chat UI App
let currentSessionId = null;
const chatContainer = document.getElementById("chat");
async function startNewChat() {
const { sessionId } = await dench.chat.createSession("App Chat");
currentSessionId = sessionId;
chatContainer.innerHTML = "";
}
async function sendMessage(text) {
appendMessage("user", text);
const responseEl = appendMessage("assistant", "");
await dench.chat.send(currentSessionId, text, {
onEvent(event) {
if (event.type === "text-delta") {
responseEl.textContent += event.data;
}
},
});
}
function appendMessage(role, content) {
const div = document.createElement("div");
div.className = `message ${role}`;
div.textContent = content;
chatContainer.appendChild(div);
chatContainer.scrollTop = chatContainer.scrollHeight;
return div;
}
Agent-Powered Data Analysis
async function analyzeData(objectName) {
const schema = await dench.objects.getSchema(objectName);
const { sessionId } = await dench.chat.createSession("Data Analysis");
const result = await dench.chat.send(
sessionId,
`Analyze the ${objectName} object. It has these fields: ${schema.fields.map((f) => f.name).join(", ")}. ` +
`Query the data and provide insights.`,
{
onEvent(event) {
if (event.type === "text-delta") updateAnalysisPanel(event.data);
},
},
);
showFinalAnalysis(result.text);
}