README
¶
runtime
Single-agent gRPC runtime for OpenOtters. Runs one agent with tools, memory, and multi-session support.
Overview
The runtime is a standalone gRPC server that implements the Agentfile specification. It consumes agent directories materialized by the agentfile executor and runs them as long-lived services.
Given an agent root directory following the Agentfile filesystem layout, the runtime:
- Reads
etc/agent.yamlfor agent configuration (name, model, tools) - Loads context files from
etc/context/to build the system prompt - Discovers and loads tool binaries from
usr/bin/ - Serves a gRPC API for chat, streaming, session management, and health checks
- Persists conversation history to SQLite with configurable compaction
gRPC API
| RPC | Description |
|---|---|
Chat |
Send a prompt, get a response |
ChatStream |
Send a prompt, receive streaming events (steps, tool calls, text deltas) |
PromptObject |
One-shot structured JSON output against a supplied JSON Schema |
ListSessions |
List active conversation sessions |
ListSessionMessages |
List the persisted messages for a single session |
DeleteSession |
Delete a session and its history |
Health |
Health check (agent name, model) |
Ready |
Readiness probe |
Proto definition lives in the agentfile repo at
agent/api/v1/agent.proto
so the client (ottersd) and server (this runtime) share one source of truth.
Usage
# Start the gRPC server
runtime serve --root /path/to/agent --api-key $ANTHROPIC_API_KEY
# Send a one-shot prompt (debug)
runtime prompt --root /path/to/agent --api-key $ANTHROPIC_API_KEY "What is the weather?"
The runtime reads etc/agent.yaml from --root automatically. No need to pass --name, --model, or --tools
explicitly.
Packages
| Package | Description |
|---|---|
pkg/agent |
Agent creation (provider selection, LLM setup) and chat service |
pkg/memory |
SQLite message store and history compaction (sliding/summarize) |
pkg/tool |
Tool binary loading; argv-in, stdout-out execution |
pkg/neighbor |
Inter-agent communication helpers |
Memory Compaction
Configured via etc/agent.yaml configs:
| Key | Default | Description |
|---|---|---|
memory-strategy |
summarize |
sliding or summarize |
memory-max-messages |
20 |
Trigger threshold |
- summarize: sends oldest messages to the LLM for summarization, keeps recent half
- sliding: drops oldest messages, keeps the last N
License
See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
runtime
command
|
|
|
pkg
|
|
|
agentclient
Package agentclient is the runtime-side client to the daemon's agent-to-agent linking RPCs.
|
Package agentclient is the runtime-side client to the daemon's agent-to-agent linking RPCs. |
|
jobsclient
Package jobsclient is the runtime-side client to the openotters daemon's async-jobs API.
|
Package jobsclient is the runtime-side client to the openotters daemon's async-jobs API. |
|
memoryclient
Package memoryclient is the runtime-side client to the daemon's agent_messages table.
|
Package memoryclient is the runtime-side client to the daemon's agent_messages table. |
|
notesclient
Package notesclient is the runtime-side client to the daemon's agent_notes table.
|
Package notesclient is the runtime-side client to the daemon's agent_notes table. |
|
sessionctx
Package sessionctx threads the current chat session id through the per-call context.Context so tool callbacks can access it without the framework having to pass it explicitly through every layer.
|
Package sessionctx threads the current chat session id through the per-call context.Context so tool callbacks can access it without the framework having to pass it explicitly through every layer. |
|
tool
markdown the model reads in its tool catalogue.
|
markdown the model reads in its tool catalogue. |
Click to show internal directories.
Click to hide internal directories.