Editing Agent Chains in the Browser

You can build every Mentiko chain by writing JSON. Some people prefer that. But if you want to see the event flow, drag agents around, and test connections visually before committing anything, the chain builder in the browser does all of that.

This walkthrough covers the full editing experience -- creating a chain from scratch, configuring each agent, wiring the events, and exporting the result.

Opening the chain builder

From your Mentiko dashboard, click "Chains" in the sidebar and then "New Chain." You land on an empty canvas with a toolbar at the top and a properties panel on the right. The canvas is where you place agent nodes. The properties panel shows configuration for whatever you've selected.

If you're editing an existing chain, click its name in the chain list. The builder loads the current definition and renders each agent as a node on the canvas with connections showing the event flow.

Adding agents

Click "Add Agent" in the toolbar or double-click anywhere on the canvas. A new agent node appears with a default name.

Click the node to select it. The properties panel shows:

• Name -- the agent identifier. Used in event references and logs. Keep it lowercase with hyphens: topic-researcher, content-writer, fact-checker.
• Prompt -- the instructions this agent receives. Supports variable interpolation with {VARIABLE_NAME} syntax. Write the prompt like you're briefing a person: what to do, what format to produce, what to avoid.
• Triggers -- the events that start this agent. The first agent in a chain usually triggers on chain:start. Subsequent agents trigger on events emitted by earlier agents.
• Emits -- the event this agent produces when it completes. The last agent in a chain typically emits chain:complete.

Here's what filling in a researcher agent looks like:

Name:     topic-researcher
Prompt:   Research {TOPIC} using web sources. Produce a structured
          summary with key facts, statistics, and source URLs.
          Keep output under 2000 words.
Triggers: chain:start
Emits:    research:complete

The builder validates as you type. If you reference a trigger event that nothing emits, it shows a warning on the connection line. If two agents emit the same event, it flags the ambiguity.

Wiring events between agents

With two or more agents on the canvas, you connect them by dragging from one agent's output port (right side) to another agent's input port (left side).

When you draw a connection from the researcher to a writer agent, the builder automatically:

1. Sets the writer's trigger to the researcher's emit event (research:complete)
2. Draws an arrow showing the event flow
3. Labels the connection with the event name

You can also wire events manually in the properties panel by typing the event name directly. This is useful for complex chains where an agent triggers on events from multiple sources, or where the visual layout doesn't match the logical flow.

For parallel execution, wire multiple agents to the same trigger event. If both a fact-checker and a style-editor trigger on draft:complete, they'll run simultaneously when the draft agent finishes:

writer (emits: draft:complete)
  |
  +---> fact-checker (triggers: draft:complete)
  |
  +---> style-editor (triggers: draft:complete)

On the canvas, this looks like two arrows branching from the writer's output port to two separate agents. The builder renders parallel paths clearly so you can see the execution topology at a glance.

Configuring workspaces

Each agent runs in a workspace. Click an agent node and expand the "Workspace" section in the properties panel to configure it.

Three workspace types are available:

Local -- the agent runs in a shell session on your Mentiko host. Fast startup, full access to local files. Good for agents that need to read/write files on the host machine.

Workspace: local
Shell:     /bin/bash

Docker -- the agent runs in an isolated container. Network access, filesystem isolation, cleanup on completion. Good for agents that run untrusted code or need specific dependencies.

Workspace: docker
Image:     mentiko/workspace:latest
Network:   bridge
Cleanup:   always

SSH -- the agent runs on a remote machine via SSH. Good for agents that need access to specific hardware or environments.

Workspace: ssh
Host:      build-server.internal
User:      mentiko
Key:       /path/to/key

The builder shows a small icon on each agent node indicating its workspace type. At a glance, you can see which agents run locally, which are containerized, and which execute remotely.

Setting variables and secrets

Click the chain background (deselect all agents) to see the chain-level properties. The "Variables" section lets you define default values for interpolated variables:

TOPIC:          (empty -- provided at runtime)
MODEL:          gpt-5.4
OUTPUT_FORMAT:  markdown
MAX_TOKENS:     4000

Variables with empty defaults are required at runtime -- the user must provide them when starting the chain.

The "Secrets" section shows a checklist of available vault secrets. Check the ones this chain needs:

[x] OPENAI_API_KEY
[ ] ANTHROPIC_API_KEY
[x] SLACK_WEBHOOK_URL
[ ] DB_PASSWORD

Secrets are pulled from the vault at runtime. The builder never displays secret values -- just their names and which chains reference them.

For per-agent secret scoping, select an agent and check the secrets it needs in its individual properties panel. Unchecked secrets won't be injected into that agent's workspace.

Testing from the builder

The builder has a "Test Run" button that executes the chain with test inputs. Click it, fill in any required variables, and watch the execution in real time.

During a test run, each agent node on the canvas shows its current state:

• Gray -- waiting for trigger
• Blue -- executing
• Green -- completed successfully
• Red -- failed

Events appear as animated pulses traveling along the connection arrows. Click a completed agent node to see its output, token usage, and duration. Click a failed node to see error details and which retry attempt it was on.

Test runs use real workspaces and real LLM calls. They cost tokens. For cheaper testing, the "Dry Run" toggle simulates execution without API calls -- it validates the event flow and variable interpolation only.

JSON view and sync

The toolbar has a toggle between "Visual" and "JSON" views. JSON view shows the raw chain definition:

{
  "name": "content-pipeline",
  "variables": {
    "MODEL": "gpt-5.4",
    "OUTPUT_FORMAT": "markdown"
  },
  "secrets": ["OPENAI_API_KEY"],
  "agents": [
    {
      "name": "topic-researcher",
      "prompt": "Research {TOPIC} thoroughly...",
      "triggers": ["chain:start"],
      "emits": ["research:complete"],
      "workspace": { "type": "local" }
    },
    {
      "name": "content-writer",
      "prompt": "Write an article based on the research...",
      "triggers": ["research:complete"],
      "emits": ["chain:complete"],
      "workspace": { "type": "docker", "image": "mentiko/workspace:latest" }
    }
  ]
}

The two views are synchronized. Edit in visual mode, switch to JSON to see the change. Edit the JSON directly, switch back and see the nodes update. Useful for bulk edits -- renaming events is faster in JSON, rearranging the canvas is faster in visual.

Saving and exporting

Click "Save" and the builder writes the chain definition to your chains/ directory as a JSON file. The filename matches the chain name: content-pipeline.json.

For chains you want to share, click "Export" and choose "Marketplace Package." This bundles the chain definition with its variable declarations and secret requirements (names only, not values). The export is a portable JSON file you can import into any Mentiko instance.

When to use the builder vs. raw JSON

Use the builder when you're designing a new chain and want to see the event topology. It's faster for exploring different agent arrangements, testing connections, and validating the flow visually.

Use raw JSON when you're making precise edits to an existing chain -- changing a prompt, adjusting a retry value, adding a variable. Or when you're generating chains programmatically from templates.

Both paths produce the same output. The builder is just a visual interface over the JSON format. There's no lock-in, no proprietary format, no features that only work in one mode.

For a comparison of the two approaches, see Visual Chain Builder vs. Code-Only Workflows. To build your first chain step by step, start with Build Your First Agent Chain in 5 Minutes.