{"id":46576518,"url":"https://github.com/agentobjectmodel/agentobjectmodel.org","last_synced_at":"2026-03-07T10:01:10.085Z","repository":{"id":342390363,"uuid":"1172096889","full_name":"agentobjectmodel/agentobjectmodel.org","owner":"agentobjectmodel","description":"Agent Object Model™ (AOM)™ v0.1.0 — the spec (JSON Schemas) plus reference tools, examples, plugins, and CLIs (aom.py, aom.mjs) for validating AOM surfaces/outputs and site policies. Canonical source for agentobjectmodel.org. ","archived":false,"fork":false,"pushed_at":"2026-03-05T21:35:15.000Z","size":167,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-05T22:45:14.444Z","etag":null,"topics":["agent-object-model","ai-agents","aom","json-schema","spec"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentobjectmodel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T00:02:24.000Z","updated_at":"2026-03-05T21:35:19.000Z","dependencies_parsed_at":"2026-03-07T10:00:34.679Z","dependency_job_id":null,"html_url":"https://github.com/agentobjectmodel/agentobjectmodel.org","commit_stats":null,"previous_names":["agentobjectmodel/agentobjectmodel.org"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agentobjectmodel/agentobjectmodel.org","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentobjectmodel%2Fagentobjectmodel.org","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentobjectmodel%2Fagentobjectmodel.org/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentobjectmodel%2Fagentobjectmodel.org/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentobjectmodel%2Fagentobjectmodel.org/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentobjectmodel","download_url":"https://codeload.github.com/agentobjectmodel/agentobjectmodel.org/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentobjectmodel%2Fagentobjectmodel.org/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30212021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-object-model","ai-agents","aom","json-schema","spec"],"created_at":"2026-03-07T10:00:30.952Z","updated_at":"2026-03-07T10:01:10.071Z","avatar_url":"https://github.com/agentobjectmodel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Object Model™ (AOM)™ · Spec and tools\n\n[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/agentobjectmodel/agentobjectmodel.org/releases) [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n\u003e A task-centric, entity-driven JSON standard that gives AI agents a clean, automation-aware view of any web page or surface — with zero layout noise, clear tasks, and explicit policies.\n\n**Get the project:** Clone this repo or [download ZIP](https://github.com/agentobjectmodel/agentobjectmodel.org/archive/refs/heads/master.zip) — spec, schemas, examples, and validators in one package. Latest release: [v0.1.0](https://github.com/agentobjectmodel/agentobjectmodel.org/releases).\n\nAgent Object Model and AOM are trademarks; registration has been filed. See [Trademark Notice](static/TRADEMARK-NOTICE.md). This repo is the canonical source for the AOM spec and reference tooling (https://www.agentobjectmodel.org).\n\n---\n\n## Table of Contents\n\n- [The Problem](#the-problem)\n- [The Solution](#the-solution)\n- [Quick Start](#quick-start)\n- [Core Concepts](#core-concepts)\n- [Output Modes](#output-modes)\n- [Repository Structure](#repository-structure)\n- [Getting Started](#getting-started)\n- [Examples](#examples)\n- [tools and validators](#tools-and-validators)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Why AOM?](#why-aom)\n- [Community and Support](#community-and-support)\n\n---\n\n## The Problem\n\nAI agents browsing the web today face critical challenges:\n\n**What agents see:**\n\n- Raw HTML and DOM trees full of layout classes, ads, and tracking scripts.\n- Unstable element identifiers that change between renders.\n- No explicit description of tasks, workflows, or navigation.\n- Hidden state machines and error paths spread across multiple pages.\n\n**This leads agents to:**\n\n- Waste tokens parsing irrelevant markup.\n- Misidentify which elements are safe or important to act on.\n- Struggle with multi-step flows (login, checkout, onboarding).\n- Depend on brittle, page-specific prompts instead of reusable contracts.\n\n**Example: A simple login form**\n\nWhat the agent gets (HTML):\n\n```html\n\u003cform id=\"login_form_a8f3\" class=\"needs-validation\"\u003e\n  \u003cinput type=\"email\" id=\"email_input_x2k9\" required\u003e\n  \u003cinput type=\"password\" id=\"password_x7k1\" required\u003e\n  \u003cbutton type=\"submit\"\u003eLog In\u003c/button\u003e\n  \u003ca href=\"/account/change-password\" class=\"link-secondary\"\u003eChange password\u003c/a\u003e\n\u003c/form\u003e\n```\n\nResult: Agent wastes tokens, unclear what happens after submit or what is safe to do.\n\n---\n\n## The Solution\n\nInstead of raw HTML, agents receive a **clean, semantic AOM JSON document** with exactly what they need:\n\n```json\n{\n  \"aom_version\": \"0.1.0\",\n  \"surface_id\": \"app:auth:login\",\n  \"surface_kind\": \"screen\",\n  \"automation_policy\": \"allowed\",\n  \"purpose\": {\n    \"primary_goal\": \"Authenticate the user and establish a session.\",\n    \"user_roles\": [\"guest\", \"anonymous\"]\n  },\n  \"tasks\": [{\n    \"id\": \"login\",\n    \"label\": \"Sign in\",\n    \"description\": \"Submit credentials to authenticate.\",\n    \"default_action_id\": \"submit_login\",\n    \"input_entities\": [\"LoginCredentials\"]\n  }],\n  \"entities\": {\n    \"LoginCredentials\": {\n      \"schema\": {\n        \"username\": { \"type\": \"string\", \"required\": true },\n        \"password\": { \"type\": \"string\", \"required\": true }\n      }\n    }\n  },\n  \"actions\": [{\n    \"id\": \"submit_login\",\n    \"label\": \"Log In\",\n    \"category\": \"mutation\",\n    \"input_entities\": [\"LoginCredentials\"]\n  }]\n}\n```\n\n**Result:** Agent sees purpose, tasks, entities, and allowed actions. No layout noise; automation policy can restrict to AOM-only (READY / `allowed`) or allow more (OPEN / `open`).\n\n**AOM's answer:**\n\n- **Surfaces**: Clean JSON documents that describe a screen's purpose, tasks, entities, actions, state, navigation, and signals.\n- **Outputs**: Structured agent responses that declare thoughts, actions, and results against those surfaces.\n- **Automation policy**: Site-level and per-surface rules (`forbidden` | `allowed` | `open`) advertised via `/.well-known/aom-policy.json` and JSON-LD in `\u003chead\u003e`.\n- **Tooling**: Validators and demo agents in this repo; reference plugins and the browser extension at [aom.tools](https://aom.tools).\n\nSee [spec/v0.1.0/README.md](spec/v0.1.0/README.md) for the full formal model.\n\n---\n\n## Quick Start\n\nClone or download this repository (see **Get the project** above), then from the repo root run the commands below. You need either Python 3 or Node 18+ for the CLI.\n\n### 0. Explore examples\n\n```bash\n# View an example surface (or open the file in an editor)\ncat examples/v0.1.0/login-single/login.aom.json\n```\n\n### 1. Validate a single input and output\n\n```bash\npython aom.py validate input --file examples/v0.1.0/login-single/login.aom.json\npython aom.py validate output --file examples/v0.1.0/login-single/outputs/_login.success.output.json\n```\n\n### 2. Run bulk validation across examples\n\n```bash\npython aom.py validate all --examples-dir examples/v0.1.0\nnode   aom.mjs validate all --examples-dir examples/v0.1.0\n```\n\n### 3. Run one demo-agent case\n\n```bash\npython aom.py demo run --lang python --folder v0.1.0/login-single --test-case _login.success.output\nnode   aom.mjs demo run --lang node   --folder v0.1.0/login-single --test-case _login.success.output\n```\n\n**Sample agent output (single-shot):**\n\n```json\n{\n  \"mode\": \"single\",\n  \"action\": {\n    \"action_id\": \"submit_login\",\n    \"params\": {},\n    \"priority\": 5\n  },\n  \"meta\": { \"done\": true, \"confidence\": 0.95 },\n  \"thought\": \"Proceeding with default task action.\",\n  \"result\": { \"ok\": true, \"user_id\": \"user1234\" }\n}\n```\n\nFor the full matrix of CLI and script-level commands, see [COMMANDS.md](COMMANDS.md).\n\n---\n\n## Core Concepts\n\n| Concept | What it represents | Where to learn more |\n|--------|---------------------|---------------------|\n| **Surface** | JSON description of a screen: purpose, tasks, entities, actions, state, navigation, signals | [spec/v0.1.0/README.md](spec/v0.1.0/README.md) (`aom-input-schema.json`) |\n| **Output** | Agent's response: thought, chosen action, result, meta | [spec/v0.1.0/README.md](spec/v0.1.0/README.md) (`aom-output-schema.json`) |\n| **Automation policy** | Rules for automation: `forbidden` \\| `allowed` \\| `open` | [spec/v0.1.0/README.md](spec/v0.1.0/README.md), [spec/well-known-policy.md](spec/well-known-policy.md) |\n| **Site policy** | Well-known JSON for site-wide automation policy | `/.well-known/aom-policy.json` examples |\n| **Signals \u0026 test cases** | Built-in feedback and test cases for each surface | [spec/v0.1.0/README.md](spec/v0.1.0/README.md) (`signals.test_cases`) |\n\n### Surface sections\n\n| Section | What it tells the agent |\n|---------|-------------------------|\n| **purpose** | Why does this screen exist? What is the user's goal? |\n| **tasks** | What workflows are available? What are the steps? |\n| **entities** | What data is in play? What are the schemas? |\n| **actions** | What can the agent do? What are the inputs/outputs? |\n| **state** | Where are we in the workflow? What is the current context? |\n| **navigation** | Where can the agent go next? What are the transitions? |\n| **signals** | Are there errors, warnings, or confirmations? |\n\n### Key principles\n\n1. **Task-centric** — Organized around user goals, not UI layout.\n2. **Entity-driven** — Data structures explicit and typed.\n3. **Action-oriented** — Clear definition of what can be done.\n4. **State-aware** — Workflow position and context tracked.\n5. **Layout-free** — No CSS, coordinates, or visual information.\n6. **Semantic-only** — Pure meaning, zero presentation noise.\n7. **Automation guardrails** — `forbidden` / READY (`allowed`) / OPEN (`open`) control how agents may use the surface.\n\n---\n\n## Output Modes\n\nAOM supports two execution patterns for agent behavior:\n\n- **Single-shot** (`mode: \"single\"`): One decision, one response. Agent reads the surface, chooses an action, returns a result with `meta.done: true`. No loop.\n- **Flow** (`mode: \"flow\"`): Multi-step. Agent emits an action; runtime returns an updated surface; loop continues until `meta.done: true`.\n\nSee [spec/v0.1.0/README.md](spec/v0.1.0/README.md) and `aom-output-schema.json` for the full output contract.\n\n---\n\n## Repository Structure\n\n```\nagentobjectmodel.org/\n├── spec/\n│   ├── v0.1.0/                    # Schemas, templates, well-known policy\n│   │   ├── aom-input-schema.json\n│   │   ├── aom-output-schema.json\n│   │   ├── site-policy-schema.json\n│   │   ├── README.md\n│   │   └── templates/site-policy/\n│   └── well-known-policy.md\n├── examples/\n│   └── v0.1.0/                   # login-single, ecom-flow, _forbidden-page-template, demo-agents\n├── tools/                        # Python + Node: validate, create-outputs, testing\n├── static/                      # Badges, USAGE.md, badge-test.html, TRADEMARK-NOTICE.md\n├── .well-known/                 # Example site policy JSON\n├── aom.py                        # Python CLI\n├── aom.mjs                       # Node CLI\n└── COMMANDS.md                   # Full command reference\n```\n\nKey entrypoints: `aom.py`, `aom.mjs`, and [COMMANDS.md](COMMANDS.md).\n\n---\n\n## Getting Started\n\n### For agent developers\n\n**Goal:** Build agents that consume AOM surfaces.\n\n1. Read the [spec](spec/v0.1.0/README.md) and schemas.\n2. Run the [examples](examples/v0.1.0/) and [demo agents](examples/v0.1.0/demo-agents/).\n3. Validate surfaces and outputs with `aom validate input` / `aom validate output` / `aom validate all`.\n4. See [COMMANDS.md](COMMANDS.md) for the full CLI surface.\n\n### For site and page publishers\n\n**Goal:** Make your site AOM-ready.\n\n1. Serve `/.well-known/aom-policy.json` (see [well-known-policy.md](spec/well-known-policy.md) and [spec/v0.1.0/templates/site-policy/](spec/v0.1.0/templates/site-policy/)).\n2. Embed AOM or JSON-LD in pages where you want agent automation.\n3. Reference plugins (WordPress, Next.js, Nuxt, Gatsby, Shopify, static-site) and the browser extension are available at [aom.tools](https://aom.tools); direct downloads: [plugins and extension](#community-and-support) in Community and Support.\n4. Optional: use [policy badges](https://www.agentobjectmodel.org/static/USAGE.html) to signal automation policy to users (usage guide and copy-paste HTML on the site).\n\nIn **`automation_policy: \"allowed\"` (READY)** mode you decide which actions the agent can see and perform: if you do **not** include a password reset or change-password flow in the surface’s `tasks` / `actions`, a conforming agent cannot invoke those operations or see the associated sensitive state. You can keep higher‑risk flows on separate surfaces with stricter policy or A2H requirements.\n\n### For implementers\n\n**Goal:** Validators, create-outputs, or other tooling.\n\n1. Read the [schemas](spec/v0.1.0/) (`aom-input-schema.json`, `aom-output-schema.json`, `site-policy-schema.json`).\n2. Run the [tools](tools/README.md) (validate, create-outputs) via CLI or scripts.\n3. Use [COMMANDS.md](COMMANDS.md) for all commands and parameters.\n\n---\n\n## Examples\n\n| Example | Purpose | Location |\n|---------|---------|----------|\n| **Login single** | Single-shot sign-in surface (READY guardrails) | `examples/v0.1.0/login-single/` |\n| **Ecom flow** | Multi-step checkout flow | `examples/v0.1.0/ecom-flow/` |\n| **Forbidden page template** | Page-level no-automation | `examples/v0.1.0/_forbidden-page-template/` |\n\nDemo agents (Python + Node) that consume surfaces and produce conformant outputs live in [examples/v0.1.0/demo-agents/](examples/v0.1.0/demo-agents/).\n\nSee [examples/v0.1.0/](examples/v0.1.0/) for details and validation instructions.\n\n---\n\n## tools and validators\n\n- **Unified CLI**: `aom.py` (Python) and `aom.mjs` (Node) — validate input/output/site/all, create-outputs, demo run/test.\n- **Validators**: Python and Node against `aom-input-schema.json`, `aom-output-schema.json`, and `site-policy-schema.json`.\n- **Create-outputs**: Generate golden `*.output.json` from `*.aom.json` surfaces.\n- **Demo agents**: Reference implementations in [examples/v0.1.0/demo-agents/](examples/v0.1.0/demo-agents/) (Python + Node).\n\nQuick start: run `python aom.py --help` or `node aom.mjs --help` from the repo root. Full reference: [COMMANDS.md](COMMANDS.md) and [tools/README.md](tools/README.md).\n\n---\n\n## Roadmap\n\n- **v0.1.0 (current)** — Spec, schemas, validators, create-outputs, demo agents, site policy, automation guardrails (forbidden / READY / OPEN).\n- **Next** — Secure payloads (future, documented elsewhere); more examples. Plugins and browser extension: [aom.tools](https://aom.tools).\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n---\n\n## Contributing\n\nThis repo is the reference implementation for the AOM spec. Contributions are welcome, especially:\n\n- Improvements to the spec text and examples (keeping backwards compatibility where possible).\n- Improvements to the Python / Node reference tools, as long as behavior stays aligned with the schemas and examples.\n\n**How to contribute:**\n\n- Report issues or propose changes (spec, examples, tools).\n- Improve documentation, add examples, or enhance tools.\n- Before submitting: run validators and demo tests per [COMMANDS.md](COMMANDS.md).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [spec/v0.1.0/README.md](spec/v0.1.0/README.md) for versioning and compatibility guidance.\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE). You may use, modify, and redistribute in commercial and non-commercial projects.\n\n---\n\n## Why AOM?\n\n- **For AI agents** — Less token waste, explicit tasks and actions, automation guardrails (READY vs OPEN), support for multi-step flows.\n- **For developers** — Agent-ready surfaces, clear contracts, validators and CLI to adopt the spec quickly.\n- **For users** — More predictable agent behavior and transparency via AOM and site policy.\n\n---\n\n## Community and Support\n\n- **Spec and standards**: [standards@agentobjectmodel.org](mailto:standards@agentobjectmodel.org)\n- **Key docs**: [spec/v0.1.0/README.md](spec/v0.1.0/README.md), [spec/well-known-policy.md](spec/well-known-policy.md), [tools/README.md](tools/README.md), [COMMANDS.md](COMMANDS.md), [CONTRIBUTING.md](CONTRIBUTING.md)\n- **Trademark**: [static/TRADEMARK-NOTICE.md](static/TRADEMARK-NOTICE.md)\n- **Badges**: [Usage guide and HTML examples](https://www.agentobjectmodel.org/static/USAGE.html) — policy badges (SVG/PNG) for AOM Open, AOM Ready, No Automation. [Theme test page](https://www.agentobjectmodel.org/static/badge-test.html) (light/dark, copy-paste). Example (links to guide):\n  \u003ca href=\"https://www.agentobjectmodel.org/static/USAGE.html\"\u003e\u003cimg src=\"https://www.agentobjectmodel.org/static/aom-badges/open/aom-open.svg\" alt=\"AOM Open\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\n- **tools and integrations** (aom.tools): plugins, browser extension, and agent kits — direct downloads:\n  - **Plugins:** [WordPress](https://aom.tools/releases/aom-policy-wp.zip) · [Next.js](https://aom.tools/releases/aom-next-middleware.zip) · [Static site](https://aom.tools/releases/aom-static-site-snippets.zip) · [Nuxt](https://aom.tools/releases/aom-nuxt-middleware.zip) · [Gatsby](https://aom.tools/releases/aom-gatsby.zip) · [Shopify](https://aom.tools/releases/aom-shopify.zip)\n  - **Browser extension:** [AOM Surface Explorer (Chromium)](https://aom.tools/releases/aom-surface-explorer-chromium.zip)\n  - **Agent kits:** [Python](https://aom.tools/releases/aom-agent-kit-python.zip) · [Node](https://aom.tools/releases/aom-agent-kit-node.zip)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentobjectmodel%2Fagentobjectmodel.org","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentobjectmodel%2Fagentobjectmodel.org","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentobjectmodel%2Fagentobjectmodel.org/lists"}