Agent framework

Example page

The project, data and links on this page are made up, to show what dokk’s components can do. It does not document dokk itself.

relay runs a model in a loop: it calls tools until the task is done. This page documents the tools of a coding agent built with it, and shows one run.

Project layout #

pyproject.toml
agent/
- main.pyruns the loop
- tools.pythe tools below
- prompts/
  - system.md
tests/

Tools #

Each tool is a Python function; relay sends its JSON schema to the model.

read_file tool

Read a text file from the repository.

Paths outside the repository are refused, and so are files over 1 MB.

Parameter	Type	Description
`path` required	`string`	Path relative to the repository root.
`start`	`integer`	First line to read. Default `1`
`limit`	`integer \| null`	How many lines; null reads to the end.

JSON schema

{
  "name": "read_file",
  "description": "Read a text file from the repository.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {"type": "string", "description": "Path relative to the repository root."},
      "start": {"type": "integer", "description": "First line to read.", "default": 1},
      "limit": {"type": ["integer", "null"], "description": "How many lines; null reads to the end."}
    },
    "required": ["path"]
  }
}

run_command tool

Run a shell command in the sandbox and return its output.

Parameter	Type	Description
`command` required	`string`	The command, such as "pytest -x".
`timeout`	`integer`	Seconds before it is stopped. Default `120`
`env`	`string[]`	Extra NAME=value pairs.

JSON schema

{
  "type": "function",
  "function": {
    "name": "run_command",
    "description": "Run a shell command in the sandbox and return its output.",
    "parameters": {
      "type": "object",
      "properties": {
        "command": {"type": "string", "description": "The command, such as \"pytest -x\"."},
        "timeout": {"type": "integer", "description": "Seconds before it is stopped.", "default": 120},
        "env": {"type": "array", "items": {"type": "string"}, "description": "Extra NAME=value pairs."}
      },
      "required": ["command"]
    }
  }
}

Tip

The second tool is written in OpenAI’s format and the first in Anthropic’s: :::tool reads both.

The system prompt #

Coding agent system

You fix failing tests in a Python repository.

Run the tests first and read the failure.
Read only the files you need.
Make the smallest change that fixes it, then run the tests again.

A run #

The user asks for a fix; the agent answers after five steps.

test_defaults fails since yesterday. Can you fix it?

relay

Fixed: load_config no longer drops the title key when the file has no [site] table. All 42 tests pass.

What happened in between:

Fixing test_defaults

Ran pytest -x

FAILED tests/test_config.py::test_defaults - KeyError: 'title'

Searched the code for load_config
Read src/config.py

Edited src/config.py

-    site = data["site"]
+    site = data.get("site", {})

Ran pytest
```
42 passed in 0.81s
```

Why a trace?

Readers trust an agent more when they can see what it did. A trace is also the quickest way to document a run in a bug report.