Single-agent gRPC runtime for OpenOtters. Runs one agent with tools, memory, and multi-session support.
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
| 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.
# 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.
| 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 |
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
See LICENSE.