Skip to main content

3. Add a tool

In step 2 the agent had memory but no way to look at the world. Now you give it the ability to read files in the user's workspace. The change is one new line under tools.modules, and the agent picks up all seven filesystem tools (Read, Write, Edit, MultiEdit, Delete, Glob, Grep) automatically. We only need Read for this tutorial.

Prerequisites​

Same as step 2 (running daemon, authenticated user, DeepSeek credential deepseek_main provisioned). For this step the agent also needs a workspace - a real directory on disk it can read from. Anything works; this tutorial points at ./workspace containing a single file called notes.md.

A sample workspace​

Create the directory and put one short file in it:

bash
mkdir -p ./workspace
printf 'shopping list\n- pasta\n- tomatoes\n- olive oil\n- basil\n' \
  > ./workspace/notes.md

The file content is a plain four-item shopping list.

The YAML​

Save this as file-reader.yaml:

app.yaml
app:
  app_id: file-reader
  name: File Reader
  version: "1.0"

runtime:
  mode: conversation
  workdir_mode: auto
  max_turns: 6
  timeout: 90

agents:
  - id: main
    role: assistant
    brain:
      provider: deepseek
      model: deepseek-chat
      backend: openai_compat
      credential:
        ref: deepseek_main
        scope: per_user
        provider: deepseek
      config:
        api_key: "{{env.DEEPSEEK_API_KEY}}"
        base_url: https://api.deepseek.com/v1
      temperature: 0
      max_tokens: 512
    system_prompt: |
      You can read files in the user's workspace using the Read tool.
      When asked about a file, call Read with its path, then answer
      with a one-line summary of what's inside. Keep replies short.

tools:
  modules:
    filesystem: {}
    memory: {}
  capabilities:
    default_policy: auto

ui:
  greeting: "Ask me about a file in your workspace and I'll read it."

Deploy and chat​

bash
digitorn install file-reader.yaml
digitorn chat file-reader --workdir ./workspace

The CLI doesn't prompt for a working directory - it silently defaults a new session to whatever directory it's run from. Pass -w/--workdir explicitly (or cd ./workspace first) so the session's Read calls resolve against the directory you just created.

Live transcript​

Real exchange against a running daemon, captured by the live test client:

text
> Please read notes.md and tell me what's in it.
**notes.md** contains a shopping list with 4 items: pasta,
tomatoes, olive oil, and basil.

The session log confirms the agent fired one tool call before answering (tool_calls_count: 1 on the result event), and the token accounting shows it actually loaded the file:

text
usage: input_tokens=5786, output_tokens=22, cost_usd=0.004717

The 5786 input tokens are the system prompt + tool schemas + the file content the Read tool returned. The 22 output tokens are the one-line summary.

What changed vs step 2​

One line under tools.modules:

yaml
tools:
  modules:
    filesystem: {}            # adds Read/Write/Edit/MultiEdit/Delete/Glob/Grep
    memory: {}                # from step 2
  capabilities:
    default_policy: auto

That's all. The agent now sees the seven filesystem tools alongside its memory tools and decides on its own when to call Read.

Tightening the surface​

default_policy: auto grants every action the agent declares it needs. For a real app you usually want to be more deliberate - read-only access, no writes, no deletes. The capability block makes that explicit:

yaml
tools:
  modules:
    filesystem: {}
  capabilities:
    default_policy: block               # nothing by default
    grant:
      - module: filesystem
        actions: [read, glob, grep]     # explicit allowlist

With this version the agent can read and search files but cannot write, edit, or delete.

Going further​

  • Use Glob to find files (Glob(pattern="**/*.md")) and Grep to search inside them. Both ship with the filesystem module.
  • See the filesystem module reference for the full action list (and the hidden parameters that handle encoding, fuzzy editing, image reads, etc.).
  • For change review on top of what filesystem writes - a shadow git repo the agent commits approved edits into, with diff/approve/reject/revert per file - see the workspace module. It tracks the same real workdir on disk, not a separate virtual copy.

Next: 4. Multi-agent team - one coordinator dispatching work to specialists in parallel. Or jump to Build a RAG bot - a how-to that puts the rag module to work over a folder of markdowns.