Chat-Based Agent Builder Inside Hermes Agent

Use public-safe placeholders

Do not publish local paths, private IP addresses, API keys, profile names, or terminal screenshots with personal machine details. Use placeholders in notes, screenshots, and docs.

<YOUR_HERMES_HOME>
<YOUR_OPEN_AGENT_BUILDER_ROOT>
<YOUR_BUILDER_URL>
<YOUR_HERMES_DASHBOARD_URL>
<YOUR_API_KEY>

Architecture

Install Hermes Agent

On macOS, the desktop installer is the easiest path. You can also use the terminal installer, then reload your shell and run setup.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc
hermes
hermes setup

For Windows native setup, open PowerShell and run the installer, then reopen PowerShell and start Hermes.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)
hermes

Start the dashboard when Hermes is ready.

hermes dashboard

Write the dashboard URL as <YOUR_HERMES_DASHBOARD_URL> in public docs instead of publishing your exact local URL.

Install Open Agent Builder

Open Agent Builder is the visual workflow builder. Install it as a separate local app, then run Convex and Next.js during development.

git clone https://github.com/firecrawl/open-agent-builder.git
cd open-agent-builder
npm install
npx convex dev

In another terminal, start the Builder app.

npm run dev

If the project supports the combined script in your checkout, you can run both together.

npm run dev:all

Builder requirements

• Node.js 18 or newer.
• Git.
• A Convex account and project.
• A Clerk account and application.
• One real LLM provider you can connect through app settings or environment variables.
• Optional: a reachable Hermes backend URL if Builder Chat should call Hermes directly.

Create the integration config

Create agent-builder.config.json in the Open Agent Builder project. Treat it as a contract for the plugin and chat API, not as an installer.

{
  "builderChat": {
    "status": "ready",
    "hermesDashboardPath": "/agent-builder",
    "embeddedBuilderUrl": "${AGENT_BUILDER_ORIGIN}/?view=builder",
    "plugin": { "name": "agent-builder" },
    "chatActions": ["ask", "build", "clear"]
  }
}

The real code must read this shape and follow it. The config alone does not install the tab, start the Builder app, or create workflow nodes.

Add environment variables

Inside Open Agent Builder, add only the values needed for your setup. Keep real keys out of tutorials and screenshots.

AGENT_BUILDER_ORIGIN=http://localhost:3000
HERMES_API_BASE_URL=http://localhost:8642/v1
HERMES_API_KEY=change-me-local-dev
HERMES_AGENT_BUILDER_ROOT=/path/to/open-agent-builder

If Builder Chat should call Hermes as an OpenAI-compatible backend, enable the Hermes API server in the Hermes environment.

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
API_SERVER_CORS_ORIGINS=http://localhost:3000

Then start the gateway.

hermes gateway

Create the Hermes dashboard plugin

Create the plugin folder in your Hermes plugins directory. Windows users should use their Hermes data directory instead of copying a macOS path.

<YOUR_HERMES_HOME>/plugins/agent-builder/dashboard/
dashboard/
  manifest.json
  plugin_api.py
  dist/index.js

Create dashboard/manifest.json.

{
  "name": "agent-builder",
  "label": "Agent Builder",
  "description": "Embed Open Agent Builder inside Hermes Dashboard.",
  "icon": "Workflow",
  "version": "1.0.0",
  "tab": { "path": "/agent-builder", "position": "after:skills" },
  "entry": "dist/index.js",
  "api": "plugin_api.py"
}

Add the plugin backend

Create dashboard/plugin_api.py. Keep the backend focused on two jobs: report health and start the Builder app if the local project exists.

router = APIRouter()

@router.get("/health")
async def health():
    return {
        "ok": app_found and builder_online,
        "builderUrl": "http://localhost:3000/?view=builder"
    }

@router.post("/start")
async def start_builder():
    subprocess.Popen(["npm", "run", "dev"], cwd=str(root))

Add the plugin UI

Create dashboard/dist/index.js. The UI should check health, start Builder, and show the Builder app in an iframe when a URL is available.

function AgentBuilderPage() {
  const [builderUrl, setBuilderUrl] = React.useState(null);

  async function checkHealth() {
    const res = await fetch("/api/plugins/agent-builder/health");
    const data = await res.json();
    setBuilderUrl(data.builderUrl);
  }

  return builderUrl
    ? React.createElement("iframe", { src: builderUrl })
    : React.createElement(Button, { onClick: checkHealth }, "Check Builder");
}

Register the page with the same plugin name used in the manifest.

window.__HERMES_PLUGINS__.register("agent-builder", AgentBuilderPage);

Restart Hermes dashboard

Plugin backend routes are mounted when the dashboard starts, so restart the dashboard after adding or changing manifest.json, plugin_api.py, or dist/index.js.

hermes dashboard

If the tab does not appear, rescan plugins from your local dashboard URL.

curl <YOUR_HERMES_DASHBOARD_URL>/api/dashboard/plugins/rescan

Add Builder Chat API

Inside Open Agent Builder, create app/api/builder-chat/route.ts. The endpoint should support three actions.

export async function GET() {
  return NextResponse.json({
    ok: true,
    status: "Builder Chat ready",
    actions: ["ask", "build", "clear"]
  });
}

Builder Chat behavior

The POST route should read the prompt, chat history, attachments, current nodes, and current edges. Then it decides whether to ask, clear, or build.

if (!prompt.trim()) return ask("Tell me what workflow to build.");
if (isClearCommand(prompt)) return startOnlyCanvas();
if (isVague(prompt)) return askFollowUpQuestions(prompt);

try {
  return await callHermesLLM(enrichedPrompt);
} catch {
  return deterministicBuilder(prompt);
}

Clear commands such as clear workflow, reset canvas, and start fresh should not call the LLM.

Connect chat to the canvas

Inside the workflow builder component, send the prompt and current canvas state to /api/builder-chat. Use the response action to update the UI.

const data = await response.json();

if (data.action === "ask") showQuestions(data.questions);
if (data.action === "clear") {
  setNodes(data.nodes);
  setEdges(data.edges);
}
if (data.action === "build") {
  setNodes(data.nodes);
  setEdges(data.edges);
  saveWorkflow(data);
}

Do not create a second storage system. Use Open Agent Builder's existing workflow save handler or Convex mutation.

Recommended chat panel

• Prompt input.
• Build button.
• Clear button.
• Assistant response area.
• Optional attachment upload.
• Current workflow context included in the request.

The user should not need a separate Ask button. Ask is a backend response when the prompt does not include enough detail.

Node mapping

Troubleshooting

• If the tab does not show, check that manifest.json is inside the dashboard folder and restart hermes dashboard.
• If plugin API routes return 404, confirm "api": "plugin_api.py" is present in the manifest and restart the dashboard.
• If the Builder root is not found, set HERMES_AGENT_BUILDER_ROOT=/path/to/open-agent-builder.
• If Builder Chat always uses fallback output, confirm HERMES_API_BASE_URL, HERMES_API_KEY, and API_SERVER_ENABLED=true.
• If the iframe does not load, confirm Open Agent Builder is running and the app allows iframe embedding.

What to say publicly

This is a custom community integration pattern built with Hermes dashboard plugins and Firecrawl Open Agent Builder. It adds an Agent Builder tab, embeds the Builder app, and uses Builder Chat to ask questions, build workflow graphs, or clear the canvas.

Do not say this is an official Hermes and Firecrawl integration unless the maintainers have published it that way.

Source links

• Open Agent Builder repository
• Open Agent Builder README