Agentic Studio and Tool-Calling Guide

Overview

Agentic mode lets Studio run multi-step plans through a relay-connected orchestrator worker. Instead of one-shot model responses, the agent can choose tools, observe outputs, iterate, and return a final answer with an execution trace.

Two user entry points exist:

1. Agentic pane in Studio (dedicated run/stop panel with trace viewer).
2. Assistant -> Run as Agentic in chat, using the same backend route.

Runtime architecture

Studio browser
  -> POST /api/agentic/run (authenticated)
    -> server/agentic.js bridge
      -> relay message to AgenticStarter worker
        -> planner (Ollama)
        -> tool workers (http, memory, registry, filesystem, clouddb)
      <- answer + per-step trace
  <- JSON response for UI

The server route is a relay bridge and guardrail layer. Tool execution and planning happen in the external workers.

Prerequisites

Worker setup

1. Prepare agentic starter

Copycd agentic-starter
npm install
cp .env.example .env

2. Set core variables

CopyRELAY_URL=https://relay.yourdomain.com
AGENT_NAME=AgenticStarter
OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=qwen2.5:7b
AGENT_MAX_STEPS=6
AGENT_PLAN_RETRIES=2
AGENT_TOOL_RETRIES=2

3. Start workers

Copy# terminal 1
npm run start:tool:memory

# terminal 2
npm run start:tool:http

# terminal 3
npm run start:tool:registry

# terminal 4
npm run start:tool:filesystem

# terminal 5
npm run start:tool:clouddb

# terminal 6
npm run start:agent

Studio pane workflow

1. Open the Agentic pane in Studio.
2. Set Relay URL and Agent name (default agent name is AgenticStarter).
3. Set max steps (UI enforces 1 to 12).
4. Optionally keep Include current editor context enabled to pass file/selection/problems context.
5. Write goal and click Run goal.

The response renders as:

• Answer: final agent text.
• Trace: per-step thoughts, actions, and observations.

Pane context payload (automatic)

{
  "source": "studio-agentic-pane",
  "at": "2026-10-02T12:34:56.000Z",
  "editor": {
    "openFile": {"name":"...","type":"...","content":"..."},
    "files": [...],
    "selection": "...",
    "errors": [...],
    "problems": [...]
  }
}

Assistant workflow (Run as Agentic)

From Assistant chat, the Run as Agentic button sends the current prompt through the same API route. While running, the button switches to Stop Agentic. On cancellation it shows Agentic run stopped.

This is useful when you want to keep conversational history in Assistant while still invoking tool-calling for selected prompts.

API contract

Request: POST /api/agentic/run

Copy{
  "relay": "https://relay.yourdomain.com",
  "agent": "AgenticStarter",
  "goal": "Find latest Node LTS and save it to memory",
  "maxSteps": 6,
  "context": {"source":"manual-api-call"}
}

Response (success)

{
  "ok": true,
  "answer": "Latest LTS is ... and was saved.",
  "trace": [
    {
      "step": 1,
      "thought": "Need current release info.",
      "actions": [{"tool":"http.request","args":{"url":"..."}}],
      "observations": [{"tool":"http.request","ok":true,"output":{...}}]
    }
  ]
}

Server validation and limits

Tool-calling details

The orchestrator recognizes these tool names by default:

Example action shape

{
  "tool": "memory.set",
  "args": {
    "namespace": "research",
    "key": "latest_node_lts",
    "value": "v22.x"
  }
}

Goal templates and examples

Research + cache pattern

CopyFind the latest Node.js LTS release from official sources. Save it in memory namespace "release_cache" key "node_lts" and return a 3-line summary.

Workspace file synthesis pattern

CopyRead docs/setup.md and docs/api.md, then write a concise onboarding note to docs/quick-onboarding.md with sections: prerequisites, first run, gotchas.

CloudDB operational pattern

CopyUsing clouddb.call, list rows from project 0123... table tasks where status=todo limit 20, then produce a markdown sprint checklist.

Constrained safe prompt pattern

CopyDo not call filesystem.write or filesystem.delete. Only use filesystem.read and memory.* tools. Analyze the release notes and summarize upgrade risks.

Stop/cancel semantics

What happens when user clicks Stop

1. Browser aborts fetch for /api/agentic/run.
2. Server detects request close and aborts relay wait.
3. Server sends relay message {"function":"agent.cancel","runId":"..."}.
4. Orchestrator looks up active run by runId and aborts its controller.
5. Planner/tool loops stop at next abort check; in-flight relay asks that honor signals are cancelled.

User-visible outcomes

• Agentic pane: status becomes Agent run stopped.
• Assistant flow: message bubble becomes Agentic run stopped.

Cancellation is cooperative. If a specific external operation is not abort-aware, stop takes effect at the next checkpoint.

Trace interpretation

Each trace step contains these parts:

Debug approach: identify first step where ok: false appears, then inspect worker availability, arguments, and connectivity.

Troubleshooting

Safety and limits

• Do not expose privileged filesystem roots to agent workers unless strictly needed.
• Use least-privilege worker credentials for registry/CloudDB environments.
• Treat memory namespace data as untrusted input when reused in future runs.
• For production, add explicit allowlists for outbound HTTP domains if possible.
• Keep goal prompts bounded and explicit to reduce unintended tool actions.