runtime

README

runtime

Single-agent gRPC runtime for OpenOtters. Runs one agent with tools, memory, and multi-session support.

• runtime
  • Overview
  • gRPC API
  • Usage
  • Packages
  • Memory Compaction
  • License

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:

1. Reads etc/agent.yaml for agent configuration (name, model, tools)
2. Loads context files from etc/context/ to build the system prompt
3. Discovers and loads tool binaries from usr/bin/
4. Serves a gRPC API for chat, streaming, session management, and health checks
5. 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.