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 AGENT_MODEL registry key)
  • 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);

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 via registry keys:

Registry Key	Default	Description
AGENT_OPENAI_BASE_URL	https://api.openai.com/v1	LLM API base URL
AGENT_OPENAI_API_KEY	(required)	API bearer token
AGENT_MODEL	gpt-4.1	Default model ID
AGENT_MAX_ITERATIONS	25	Default iteration cap
AGENT_SYSTEM_PROMPT_ASSET_PATH	agent/system-prompt.md	Default system prompt resource
AGENT_POOL_SIZE	4	Concurrent agent worker threads
AGENT_RUN_TIMEOUT_MS	600000	Default timeout (10 min)
AGENT_TEMPERATURE	(unset)	Default sampling temperature

Set these via the MCP registry_set tool or from a script:

diesel.setRegistryValue("AGENT_OPENAI_API_KEY", "sk-...");
diesel.setRegistryValue("AGENT_MODEL", "gpt-4.1");

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