From 56f1f5dd62ae646baa7a87830b046e4a99a0c016 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Tue, 4 Aug 2026 20:03:26 +0200 Subject: [PATCH] usage: strip technical content, link to whitepaper and ellie --- doc/usage.md | 120 +++------------------------------------------------ 1 file changed, 6 insertions(+), 114 deletions(-) diff --git a/doc/usage.md b/doc/usage.md index 78a0245..4c0b27b 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -187,119 +187,11 @@ state transition via `statewait` — zero CPU when idle. --- -## Generation parameters +## Other front-ends -Parameters are set in the agent config JSON and can be overridden at runtime by -writing `key=value` to the agent config. Runtime overrides take precedence: - -```sh -echo "temperature=0.3" | ollie-9p write session/mysession/agent/{aname}/cfg -``` - -| Key | Type | Description | -|---|---|---| -| `maxTokens` | int | Max output tokens (0 = no limit) | -| `maxCompletionTokens` | int | OpenAI o-series alternative to maxTokens | -| `temperature` | float | Sampling temperature | -| `topP` | float | Nucleus sampling threshold | -| `topK` | int | Top-K sampling (Anthropic, Ollama) | -| `minP` | float | Min-P sampling (Ollama) | -| `topA` | float | Top-A sampling (Ollama) | -| `frequencyPenalty` | float | Frequency penalty | -| `presencePenalty` | float | Presence penalty | -| `repetitionPenalty` | float | Repetition penalty (Ollama) | -| `reasoning` | int | Thinking budget in tokens (Anthropic); 0 = disabled | -| `reasoningEffort` | string | `low`, `medium`, `high` (OpenAI o-series) | -| `includeReasoning` | bool | Include reasoning in response (OpenRouter) | -| `responseFormat` | string | `json_object`, `text`, etc. (OpenAI) | -| `stop` | string | Comma-separated stop sequences | -| `verbosity` | string | Output detail level (internal, not sent to API) | - -Example agent config: - -```json -{ - "prompt": "You are a helpful assistant.", - "temperature": 0.7, - "topP": 0.95, - "reasoning": 10000, - "stop": ["\n\n"] -} -``` - -## Sandbox - -Every `shell` invocation (and promoted tool call) runs inside a Landlock sandbox -configured by `~/.config/ollie/sandbox/.yaml`. The sandbox wraps each -invocation as a new command, so config changes (e.g. granting access to an -additional directory) take effect on the next call without restarting the server -or session. - -## Multi-agent workflows - -Two patterns cover most multi-agent use cases: ephemeral subagent delegation for -independent parallel subtasks, and persistent concurrent sessions for workflows -that need coordination or long-lived state. - -### Subagent delegation - -`subagent_spawn` forks N ephemeral agents with a shared prompt, waits for all to -finish, and returns their results concatenated. Use it when work splits into -independent subtasks: - -```json -{ - "steps": [{"tool": "subagent_spawn", "args": "-n 3 summarize this module"}] -} -``` - -**Flags** - -| Flag | Description | -|---|---| -| `-n N` | Number of subagents to spawn (default: 1) | -| `-agent A` | Agent config for each subagent | -| `-backend B` | Backend override | -| `-model M` | Model override | -| `-cwd DIR` | Working directory for subagents (default: `pwd`) | -| `-keep` | Do not remove sessions after collecting results | - -### Concurrent sessions - -For long-lived parallel agents, create named sessions and pass prompts between -them via the filesystem: - -```sh -o write session/new "name=writer cwd=$PWD" -o write session/new "name=reviewer cwd=$PWD" -agent=$(o ls session/writer/agent | grep -v '^new$') -o write "session/writer/agent/$agent/prompt" "Draft a design doc" -o read "session/writer/agent/$agent/chat" # read writer's response -``` - -Key files per agent: - -| File | Mode | Description | -|---|---|---| -| `prompt` | write | Queue a new turn; enqueued if agent is busy | -| `statewait` | read (blocking) | Blocks until state changes; returns new state | -| `state` | read | Current state: `idle`, `running`, `failed: ` | -| `chat` | read | Full conversation history | -| `context` | read | Full message history as JSONL | -| `offset` | read | Byte position in `chat` after the last user prompt | -| `plan` | r/w | Scratch space for agent planning | -| `prompt.prev` | read | The last submitted prompt | -| `env` | read | Session environment variables | -| `cost` | read | Cumulative cost in USD | - ---- - -> **For implementers**: The raw 9P filesystem reference, store federation, tool -> discovery internals, context inspection, system prompt overrides, and -> predefined workflow scripts are documented in [doc/whitepaper.md](whitepaper.md). - -## Alternative front-ends - -- **[ellie](ellie.md)** — Emacs front-end (session tree, chat, multi-agent) +- **[ellie](ellie.md)** — Emacs session tree, chat, multi-agent - **KDE** — plasmoid, standalone GUI, Kate plugin, KRunner, system tray -- **Web** — built-in HTTP server (see `olliesrv -web`) \ No newline at end of file +- **Web** — built-in HTTP server (see `olliesrv -web`) + +For technical details (generation parameters, sandboxing, multi-agent workflows, +tool discovery, and the raw 9P filesystem), see [doc/whitepaper.md](whitepaper.md). \ No newline at end of file