5.5 KiB

Raw Permalink Blame History

Prompting Architecture

Ollie builds one system-prompt preamble for each active agent runtime. Prompting is assembled at agent selection or reload time, then reused across turns while the runtime remains active.

Runtime flow

agent config + embedded system prompt + environment
                    │
                    ├─ resolve prompt files
                    ├─ list tools and convert schemas
                    ├─ render named preamble sections
                    └─ create Runtime
                         │
                         ├─ system message: Preamble
                         └─ each user turn: UserPrompt + input

agent.BuildRuntime is the assembly point. It creates four ordered preamble sections:

system — the embedded default prompt, or the configured systemPrompt override.
env — the current working directory, platform, Git-repository flag, and sandbox.
agent — the resolved contents of the configured prompt entries.
tools — descriptions and .meta documentation for the tools returned by the tool server.

Empty sections are skipped. Non-empty sections are joined with one newline. The resulting string is sent as the provider’s system message before conversation history.

Agent configuration

Agent JSON is loaded from the installed agent configuration directory. The relevant fields are:

Field	Behavior
`prompt`	A string or array of file paths concatenated into the agent section.
`userPrompts`	A string or array of file paths concatenated and prepended to every user turn.
`systemPrompt`	Replaces the embedded base system prompt with a resolved file.
`autoLoad`	Selects tools loaded by the tool server before runtime construction.
`tools`	Disables tool discovery and execution when explicitly set to `false`.
`maxSteps`	Limits tool-call rounds in one turn; zero means unlimited.
`compactionModel`	Selects the model used for history compaction.
generation fields	Configure backend/model sampling and token limits.

prompt and userPrompts accept either a single path or an array. Environment variables are expanded in paths and file contents. Missing files are retried with a .md suffix and then skipped. A leading ! remains supported for legacy command entries; the command runs with the agent working directory and its stdout becomes prompt text.

The default configuration uses installed prompt files under $XDG_CONFIG_HOME/ollie/prompts. Runtime data is installed by make install-data; source prompt templates live under data/prompts.

Tool rendering

When tools are enabled, BuildRuntime calls the configured ToolsrvConn to obtain the agent’s currently loaded tool metadata and its registry revision. The default profile starts with only client_9p; additional tools are loaded through the agent ctl file and become available after the runtime refreshes its schemas. The metadata becomes both:

the backend function/tool definitions, with dispatch flags added to each schema; and
the rendered # Tools preamble section.

RenderTools sorts tools by name, omits remote-server entries, and renders each local tool’s .meta prompt when present. It falls back to the description when no prompt is available. The current implementation combines the tool listing and documentation instead of maintaining separate listing and schema-dump sections.

Tool restrictions are not implemented in the prompt builder. The tool server determines which tools are available, and the runtime uses that same returned set for both execution schemas and prompt text.

Per-turn prompting

Runtime.UserPrompt is not part of the system preamble. Before a turn is submitted, executeTurn prepends the resolved userPrompts content to the user input:

resolved user prompts

user input

Queued prompts, injected prompts, and tool results then participate in the normal agent history and turn loop. The system preamble remains stable until the runtime is rebuilt.

System prompt resolution

ResolveSystemPrompt selects the configured systemPrompt override when present. Otherwise it uses the embedded prompts.DefaultSystemPrompt, generated from cmd/olliesrv/internal/prompts/system_prompt.md.

The base prompt is intentionally generic. Agent-specific behavior belongs in the agent’s prompt files; active per-user rules belong in userPrompts. The system prompt also documents the common 9P runtime and tool-loading interface shared by agents.

Context and compaction

The runtime passes the preamble and message history to the backend. The agent maintains history separately from prompt assembly. When history reaches configured limits, compaction produces a summary and the runtime continues with the compacted history plus the same system preamble.

The systemprompt 9P file exposes the current rendered preamble for inspection. It is the assembled runtime value, not a separate prompt source.

Source locations

Responsibility	Source
Agent configuration types	`cmd/olliesrv/internal/agent/agent_config.go`
Prompt file and environment expansion	`cmd/olliesrv/internal/agent/prompt_resolver.go`
Preamble and runtime construction	`cmd/olliesrv/internal/agent/runtime.go`
Per-turn user-prompt injection	`cmd/olliesrv/internal/agent/turn.go`
Embedded default system prompt	`cmd/olliesrv/internal/prompts/system_prompt.md`
Installed agent configuration	`data/agents/*.json`
Installed prompt templates	`data/prompts/*.md`

5.5 KiB Raw Permalink Blame History Unescape Escape