Skip to content

architecture.md

Latest commit

 

History

History
76 lines (60 loc) · 2.57 KB

architecture.md

File metadata and controls

76 lines (60 loc) · 2.57 KB
Raw

Architecture

OpAgent separates durable state, execution, wire interoperability, and host integration. The dependency direction stays toward the Protocol and Runtime; hosts do not become dependencies of the kernel.

flowchart LR
  Client["CLI, app, or service"] --> Server["opagent-server\nHTTP + SSE"]
  Client --> Host["Embedded Go host"]
  Server --> Runtime["opagent-runtime"]
  Host --> Runtime
  Runtime --> Protocol["opagent-protocol"]
  Runtime --> Packages["Agents, Tools, Skills"]
  Runtime --> State["Thread JSONL + workspace files"]
  Runtime --> Policy["Permissions + sandbox"]
Loading

Runtime

The Runtime scans <baseDir>/tools, then skills, then agents, so agent references resolve against already discovered dependencies. It starts endpoint processes, assembles prompts, runs model turns, delegates to subagents, and persists thread history. In v0.1 one Runtime owns the process-wide registries.

Protocol

The Protocol combines MCP-compatible lifecycle and transport primitives with OpAgent operations for agents, nodes, threads, permissions, schedules, and notifications. Go is the reference SDK; TypeScript exposes the same wire shapes. Unknown metadata is preserved when forwarding.

Generic Server

The Server embeds a Runtime and exposes only a loopback HTTP surface. It creates threads, submits messages, interrupts turns, reads snapshots, and translates Runtime notifications to SSE. Its bounded replay memory is transient; the Runtime's thread JSONL remains authoritative.

Packages

An Agent lives under agents/<name>/.agent/AGENT.md. A Tool uses TOOL.md; a Skill uses SKILL.md. Manifests contain YAML front matter plus readable Markdown instructions. Relative executable and component paths resolve from the package, while @agents, @tools, and @skills references resolve from the Runtime base directory.

Data layout

Standalone state defaults to ~/.opagent:

~/.opagent/
  agents/
  skills/
  tools/
  configs/user/
  threads/
  objects/
  logs/
  run/local-connection-token
  workspace/

All derived paths use the normalized baseDir. OPAGENT_BASE_DIR is the only standalone environment override.

Trust boundaries

  • HTTP access is loopback-only and capability-token authenticated.
  • Runtime filesystem/process decisions use a permission snapshot owned by the Runtime, not request-supplied policy objects.
  • Remote nodes and system services are denied unless host authorization hooks accept them.
  • Host-managed model or identity configuration must enter through host hooks; local configuration cannot impersonate managed authority.