usage: strip technical content, link to whitepaper and ellie
This commit is contained in:
Ollie Agent
parent
04a29a71fd
commit
56f1f5dd62
120
doc/usage.md
120
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/<name>.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: <reason>` |
|
||||
| `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`)
|
||||
- **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).
|
||||
Loading…
Reference in New Issue