Agents

What a Jettson agent is, its lifecycle, and the computer it gets.

An agent in Jettson is one task that runs inside its own persistent computer. The agent owns a filesystem, a reasoning model, long-term memory, and a browser, shell, and outbound network. It has a beginning, a middle (sometimes seconds, sometimes hours), and a terminal state.

Anatomy

| Part | What it is | | --- | --- | | Task | The prompt you provide on start. Plain English, up to 4000 characters. | | Computer | The isolated Linux environment the agent boots into — 1GB workspace, reasoning model, built-in tools. | | Reasoning | jettson-6.0 plans the work, decides which tools to call, summarizes results. | | Tools | Built-in: browser, shell, files, HTTP, memory. The agent can install more at runtime. | | Memory | The user's persistent knowledge pool; the agent reads and writes it. | | final_result | The structured output the agent returns when done. |

Lifecycle

Every agent moves through this state machine:

text
spawning ─────► running ─────► completed
              │                │
              ├─────► stopped  (user cancellation)
              │
              └─────► error    (max duration, internal failure)
  • spawning — the request landed; the agent's computer is provisioning. Lasts ~500ms on a warm-pool hit, 10-15s cold.
  • running — the computer is up, the agent is reasoning, and tool calls are flowing. The Console shows live events.
  • completed — the agent emitted a terminal "end" event. final_result is populated.
  • stopped — you cancelled it (via DELETE /api/v1/agents/{id} or the Console's Stop button).
  • error — exceeded maxAgentDurationMinutes, hit a hard cap, or an internal failure surfaced.

Anatomy of a task prompt

A useful task prompt has three pieces, in order:

  1. What to do. State the goal clearly. "Research Acme Corp and return a structured dossier."
  2. What to use. Reference specific tools by name when you want them — e.g. "Use jettson_browser_navigate first."
  3. What to return. Specify the output shape. "Return JSON with these fields: …"

Jettson's prompt cache means the system prompt + tool definitions are cached after the first call — your task is the only thing that varies, so token costs stay low even on agents you spawn thousands of times.

Limits

Each plan caps three dimensions of agent runs:

| Plan | Concurrent agents | Max duration per run | Agent-hours/month | | --- | --- | --- | --- | | Free | 1 | 30 min | 50 | | Pro | 3 | 2 hours | 1,000 | | Scale | 20 | 4 hours | unlimited |

See Plans and quotas for the complete enforcement matrix.

Reasoning

jettson-6.0 is the public model name for the agent's reasoning. We pin the underlying provider, version, and parameters server-side so your code never depends on a specific upstream model — you upgrade by deploying, not by changing every prompt.

The reasoning loop runs like this:

  1. Reads the task + any recalled memories.
  2. Either emits text (final result) or a tool_use block requesting a tool call.
  3. The agent's computer executes the tool and feeds the result back.
  4. Repeats until end_turn or the iteration cap (20).

Most agents finish in 3-8 iterations. The cap is there so a runaway loop can't burn unbounded tokens.

Idempotency and retries

Agent spawns are not idempotent — two POSTs to /api/v1/agents create two agents. If you need at-most-once semantics, dedupe on your side before calling Jettson.

If a spawn fails (rate limit, quota, transient infrastructure), the error response tells you whether it's safe to retry. See errors.