Agent API

DieselEngine includes a built-in autonomous agent system. From your scripts, you can spawn LLM-powered agent runs that have access to every MCP tool registered on the platform — file operations, database queries, ingress management, script execution, and more.

Overview

An agent run is an autonomous loop where:

1. The LLM receives a task description and a system prompt
2. It decides which MCP tools to call
3. Tool results are fed back to the LLM
4. The loop continues until the task is complete or the iteration limit is reached

Agent runs execute in-process — tools are called directly via the internal McpToolRegistry, bypassing HTTP and auth. This makes them fast and gives them full platform access.

Blocking: diesel.runAgentTask(options)

Start an agent run and wait for it to complete. This blocks the calling script until the agent finishes or times out.

• Parameters: options: object
  • task: string — (required) the task description for the agent
  • maxIterations?: number — maximum tool-call iterations (default: 25, hard max: 100)
  • timeoutMs?: number — wall-clock timeout in milliseconds (default: 600000 = 10 min)
  • model?: string — LLM model to use (default from the resolved provider profile)
  • systemPromptOverride?: string — custom system prompt (replaces the default)
  • temperature?: number — sampling temperature
• Returns: object — the run snapshot

const run = diesel.runAgentTask({
  task: "Create a GET endpoint at /api/stats that returns row counts for every table in the engine schema",
  maxIterations: 15,
  timeoutMs: 120000
});

console.log("Status:", run.status);   // "completed" | "failed" | "cancelled" | "max_iterations"
console.log("Result:", run.result);

Non-Blocking: diesel.startAgentTask(options)

Start an agent run and return its UUID immediately without waiting.

• Parameters: same as runAgentTask
• Returns: string — the run UUID

const uuid = diesel.startAgentTask({
  task: "Refactor the ItemService to add pagination support",
  maxIterations: 20
});
console.log("Agent run started:", uuid);

Check Status: diesel.getAgentRun(uuid)

Get a snapshot of an agent run, including its status, messages, and tool calls.

• Parameters: uuid: string
• Returns: object — run snapshot

const run = diesel.getAgentRun(uuid);
console.log("Status:", run.status);
console.log("Iterations:", run.iterations);

Cancel: diesel.cancelAgentRun(uuid)

Request cooperative cancellation of a running agent task. The current LLM call is aborted and the run transitions to cancelled status.

• Parameters: uuid: string

diesel.cancelAgentRun(uuid);

Continue a Previous Run

Create a new agent run that continues a previous terminal run, inheriting its conversation transcript.

diesel.getAgentService().continueRun(previousRunUUID, additionalUserMessage)

Starts a new run that picks up where the previous run left off. Appends the additional user message and continues the ReAct loop.

• Parameters:
  • previousRunUUID: string — UUID of the previous (terminal) run
  • additionalUserMessage: string — optional message to append; if null/blank, uses a default "Continue where you left off"
• Returns: string — UUID of the new run

const agent = diesel.getAgentService();

// Continue a previous run
const newUuid = agent.continueRun(previousUuid, "Also add error handling for edge cases");
console.log("Continuation run started:", newUuid);

diesel.getAgentService().continueRun(previousRunUUID, additionalUserMessage, requestTemplate)

Same as above, but accepts an AgentRunRequest as a template so you can carry forward restrictions (allowed tools, model, etc.).

• Parameters:
  • previousRunUUID: string
  • additionalUserMessage: string
  • requestTemplate: object — AgentRunRequest for configuration overrides

const req = new (Java.type('com.dieselengine.diesel.models.AgentRunRequest'))("Continue work");
req.maxIterations = 15;
const newUuid = agent.continueRun(previousUuid, "Please also write tests", req);

List Recent Runs

diesel.getAgentService().listRuns(limit)

Returns the most recent agent runs (newest first), capped at the given limit.

• Parameters: limit: number — maximum number of runs to return
• Returns: AgentRun[] — list of run snapshots

const agent = diesel.getAgentService();
const runs = agent.listRuns(10);
for (const run of runs) {
  console.log(run.uuid, run.status, run.task);
}

Run Status Values

Status	Description
running	Agent is currently executing
completed	Agent finished the task successfully
failed	Agent encountered an error
cancelled	Run was cancelled via cancelAgentRun
max_iterations	Iteration limit reached before completion
timeout	Wall-clock timeout exceeded

Common Patterns

Fire-and-Forget

// Kick off an agent and don't wait
diesel.startAgentTask({
  task: "Review all ingress handlers and add input validation where missing"
});

Poll Until Complete

const uuid = diesel.startAgentTask({
  task: "Generate a test data set for the users table",
  maxIterations: 10
});

// Poll every 5 seconds
let status = "running";
while (status === "running") {
  java.lang.Thread.sleep(5000);
  const run = diesel.getAgentRun(uuid);
  status = run.status;
  console.log("Agent status:", status);
}

const finalRun = diesel.getAgentRun(uuid);
console.log("Result:", finalRun.result);

Triggered by Cron

// /cronjobs/nightly-agent-review.js
const run = diesel.runAgentTask({
  task: `
    Check the error logs from the past 24 hours.
    If there are recurring errors, create a summary and
    add it as an idea to the "Bugs" board in the Backlog column.
  `,
  maxIterations: 20,
  timeoutMs: 300000  // 5 minutes
});

console.log("Nightly review:", run.status, run.result);

Chained Agents

// First agent creates the endpoint
const step1 = diesel.runAgentTask({
  task: "Create a POST endpoint at /api/orders that accepts {itemId, quantity} and creates an order",
  maxIterations: 15,
  timeoutMs: 120000
});

if (step1.status === "completed") {
  // Second agent writes tests
  const step2 = diesel.runAgentTask({
    task: "Write tests for the POST /api/orders endpoint that was just created",
    maxIterations: 10,
    timeoutMs: 120000
  });
  console.log("Tests:", step2.status);
}

Custom System Prompt

const run = diesel.runAgentTask({
  task: "Implement the feature described in idea XYZ",
  systemPromptOverride: `
    You are a backend developer working on the DieselEngine platform.
    Follow these rules:
    - Always use prepared statements for database queries
    - Always validate input in ingress handlers
    - Add JSDoc comments to all exported functions
    - Use the delegation pattern: thin handlers, service classes for logic
  `,
  maxIterations: 25
});

Configuration

Agent behavior is configured through LLM Provider profiles. A request uses its explicit profileUUID when supplied; otherwise it uses the provider marked default. If no default provider is configured, the request fails before the run starts.

Provider profiles define the OpenAI-compatible base URL, API key, model, and optional defaults for temperature and max iterations. The built-in system prompt is loaded from agent/system-prompt.md; worker pool size, run timeout, and the hard iteration cap are runtime constants.

REST Endpoints

Agent runs can also be managed via HTTP (all gated by x-auth-token):

Method	Path	Description
POST	/agent/tasks	Start a run
GET	/agent/tasks?limit=50	List recent runs
GET	/agent/tasks/{uuid}	Get full run snapshot
POST	/agent/tasks/{uuid}/cancel	Cancel a run
GET	/agent/tasks/{uuid}/wait?timeoutMs=60000	Long-poll until terminal