Agent System
Jan Agent includes a built-in autonomous agent that uses a ReAct (Reason + Act) loop to solve tasks by combining LLM reasoning with tool execution. See Core Concept for how the agent framework's trait system works under the hood.
How it works
The agent follows a simple cycle:
- Reason — The LLM analyzes the current context and decides what to do next
- Act — The agent executes a tool call (read a file, run a command, search the web)
- Observe — The tool result is fed back into the context
- Repeat — Until the task is complete or the agent decides to stop
User prompt │ ▼┌─────────┐ ┌──────────┐ ┌───────────┐│ Reason │────▶│ Act │────▶│ Observe ││ (LLM) │◀───│ (Tool) │◀───│ (Result) │└─────────┘ └──────────┘ └───────────┘ │ ▼Final response
Built-in tools
| Tool | Description |
|---|---|
web.search | Search the web via Brave Search or DuckDuckGo |
http.fetch | Fetch any URL (GET, 256 KB truncation) |
code.exec | Execute JavaScript, Python, or Bash |
robot.* | Robot movement and vision commands |
Tools are plugins — they can be added, removed, or replaced without changing the agent. See the plugin system docs for how to create your own.
Running the agent
Interactive TUI mode
jan agent chat --api-url http://localhost:6767/v1
This launches a terminal UI with:
- Real-time token streaming
- Tool call visualization
- Resource monitoring (VRAM, model memory)
/clearcommand to reset context
One-shot mode
jan agent chat --api-url http://localhost:6767/v1 -m "Explain what src/main.rs does"
The agent processes the prompt, executes any necessary tool calls, and prints the result.
With a local model (auto-serve)
jan agent chat --model janhq/Jan-code-4b-gguf
When no --api-url is provided but a model is specified, Jan Agent automatically starts a local model server before launching the agent.
Tool sandbox
Tool execution can be sandboxed at different isolation levels, controlled by the Runtime Policy:
| Mode | Isolation | Used by |
|---|---|---|
| Host | None — direct execution | Robot tools, trusted commands |
| WASM | Process + fuel metering | web.search, http.fetch |
| MicroVM | Full VM via microsandbox | code.exec (Python, Bash) |
The WASM sandbox provides:
- Fuel metering — limits CPU cycles per tool invocation
- Wall-clock timeout — kills long-running tools
- Capability-based permissions — tools declare what they need (filesystem, network, etc.)
The sandbox backend is selected by the runtime policy configuration. See Runtime Policy for how to configure sandbox modes per tool.
Mounting directories
Use --mount to give the agent access to specific directories:
jan agent chat --api-url http://localhost:6767/v1 --mount /path/to/project
Multiple --mount flags can be provided to expose several directories.