Your first agent

Build a multi-turn LLM agent with tools, running on your local machine.

A Flux agent is a YAML file. Point it at a model, give it tools, and it runs durably — survives restarts, holds memory across turns, and pauses for approval on demand.

This page builds a local Ollama agent with file-system tools. No API keys needed; runs entirely offline.

  1. Pull an Ollama model

    ollama pull qwen3:8b

    This downloads a small (~5 GB) capable local model. To use a hosted provider instead, see Installation → Optional extras.

  2. Define the agent

    Create assistant.yaml:

    name: my-assistant
model: ollama/qwen3:8b
description: Local assistant with read-only file access
system_prompt: |
  You are a helpful assistant running on a local Ollama model.
  When the user asks about code or files, use the file tools to read
  them before answering. Be concise.

tools:
  - files:
      workspace: .

max_tool_calls: 10
max_tokens: 4096
stream: true

    One tool group: files scoped to the current directory. The model can read files within . but can’t write or escape the workspace.

  3. Start the Flux server and a worker

    In one terminal:

    flux start server

    In a second terminal:

    flux start worker my-worker

    The worker executes the agent loop. The server holds state and exposes it via API and CLI.

  4. Register and start the agent

    In a third terminal:

    flux agent create my-assistant --file assistant.yaml
flux agent start my-assistant --mode terminal

    mode terminal opens an interactive REPL — you type, the agent responds, tool calls visible inline.

    Try: What files are in this directory? Read the most interesting one.

    The agent calls files to list, then reads, then responds.

  5. See the durable history

    Stop the agent with Ctrl+D, then:

    flux agent session list my-assistant
flux agent session show <session-id>

    Every turn is recorded: user message, model response, tool call, tool result. Resume the session later with flux agent start my-assistant --session <session-id>.

What to remember

Sessions persist automatically — you don’t have to do anything for durability. The YAML format is the full agent definition; there’s no separate code file unless you add custom tools.

Next