Introduction
OAM — Object Agent Mapping — is the framework for giving agents, services, and automation structured and policy-aware access to data.
Where an ORM (Object Relational Mapping) maps application objects to relational rows, OAM maps agent intent to data operations. The framework controls how an agent discovers, accesses, and works with data — and enforces those rules consistently across languages and deployment patterns.
ROAM is the runtime that implements OAM. It provides identity-aware execution, policy enforcement, and agent-ready context across application and service boundaries.
Schema Modes
OAM defines three operating modes that determine how an agent interacts with data:
| Mode | Description | Access |
|---|---|---|
| Data-First | The agent discovers the database schema at runtime through introspection. No application model registration required. Best for exploring legacy or external databases. | Read-only |
| Code-First | Only tables explicitly registered by the application are accessible. The application controls validation and access rules. Best when the codebase owns the data. | Read-write |
| Hybrid | Registered models take precedence; unknown tables fall back to introspection. Provides coverage without sacrificing safety where code coverage ends. | Read-only |
Choose Data-First when agents need to explore data without committing to a code model. Choose Code-First when your application owns the data and must enforce validation rules. Use Hybrid when your codebase covers some tables but you still want introspection for the rest.
What This Book Covers
- Architecture explains how ROAM fits into application, service, and event-driven systems.
- Runtime Context explains how request metadata and runtime augmentation travel with execution.
- Contributing explains how to propose changes to the public runtime, SDKs, and documentation.
- SDK Guides help you choose the best starting point for Python and .NET integrations.
Where ROAM Fits
ROAM is designed for teams that want to:
- add policy-aware execution to application and service workflows
- carry stable identity and organization context through runtime operations
- integrate agent-driven or automation-driven behavior without rewriting existing systems
- standardize public integration contracts across multiple languages
Operating Patterns
ROAM typically appears in one of two patterns:
- Application-intercepted flows where ROAM validates and enriches requests as they move through an API or service boundary.
- Event-driven flows where ROAM observes or participates in runtime decisions driven by messages, RPC calls, or automation pipelines.
Quick Links
- roam-public for the public Rust core and shared runtime contract
- roam-python for Python integrations and automation workflows
- roam-dotnet for .NET services and typed enterprise integrations
Suggested Starting Path
- Start with Architecture Overview to understand the public runtime model.
- Read Runtime Context if you need request metadata and runtime-augmentation guidance.
- Choose your SDK: Python or .NET.
- Use API Reference when you are ready for package and protocol details.