open-managed-agents AGENTS.md

Agents Guide

This document covers the core concepts, lifecycle, and configuration of agents in Open Managed Agents.

---

Core Concepts

Open Managed Agents is built around a meta-harness architecture with four key abstractions:

Agent

An agent is a configuration object that defines what an AI assistant can do. It specifies the model, system prompt, available tools, skills, and optional connections to other agents or MCP servers.

Agents are versioned — every update creates a new version. Sessions bind to a specific agent version at creation time.

Session

A session is a running conversation between a user and an agent. It owns an append-only event log stored in a Durable Object backed by SQLite. Sessions are the unit of state — agents themselves are stateless configurations.

Sessions can be streamed in real-time via SSE, resumed after crashes, and archived when complete.

Environment

An environment defines the execution sandbox — what packages are installed, what networking is allowed, and what container image to use. Environments are reusable across sessions and agents.

Vault

A vault is a secure credential store. Credentials in vaults are never exposed to sandboxes — they're injected via an outbound proxy that intercepts HTTP requests and adds authentication headers transparently.

---

Agent Lifecycle

                    ┌──────────┐
                    │  Create   │  POST /v1/agents
                    └────┬─────┘
                         │
                    ┌────▼─────┐
              ┌────►│  Active   │◄────┐
              │     └────┬─────┘     │
              │          │           │
         ┌────┴───┐ ┌───▼────┐ ┌───┴─────┐
         │ Update  │ │ Archive│ │ Sessions│
         │ (new    │ │        │ │ use it  │
         │ version)│ └───┬────┘ └─────────┘
         └─────────┘     │
                    ┌────▼─────┐
                    │ Archived  │
                    └──────────┘

1. Create — POST /v1/agents with name, model, system prompt, and tools
2. Use — Create sessions referencing the agent by ID
3. Update — PUT /v1/agents/:id creates a new version; existing sessions keep their original version
4. Archive — POST /v1/agents/:id/archive soft-deletes the agent