agent-manifest

A minimal, machine-readable JSON document that describes an entity (business or digital) in a way AI agents can read, reason about, and act on.

This repository contains an intentionally small draft of that idea, plus a runnable demo showing why such a manifest matters.

What problem this addresses

AI agents can converse fluently, but they do not reliably understand what real-world entities can actually do.

Today, agents must:

• scrape websites built for humans
• rely on platform-specific integrations
• guess capabilities from unstructured text

An agent-manifest is a simple alternative: a small, explicit description of an entity’s capabilities and interaction options, published in a standard, agent-readable form.

What this repository contains

• schema/
  Draft JSON Schema for agent-manifest

• examples/
  Example manifests for different entity types

• notes/
  Design decisions, constraints, and open questions

• tools/simple_agent/
  A minimal, runnable demo showing how an agent’s behavior changes when a manifest is present versus absent

What this demo proves

The included simple_agent demo shows a concrete, testable claim:

The same agent, given the same user request, behaves differently solely because an agent-manifest exists.

No UI scraping.
No custom integrations.
No platform-specific logic.

The manifest itself is the causal input.

Design principles

• Small and readable
  Manifests should be easy for both humans and agents to inspect.

• Descriptive, not authoritative
  A manifest advertises potential capabilities; it does not guarantee availability.

• Agent-first
  Field choices favor agent reasoning over human presentation.

• No premature complexity
  Authentication, payments, trust scoring, and reputation are explicitly out of scope for this draft.

If something feels “too simple,” that is likely intentional.

Validating a manifest

This project uses standard JSON Schema.

You can validate a manifest using any JSON Schema validator, for example:

• https://www.jsonschemavalidator.net/

Or locally with Python:

python3 - <<'EOF'
import json
from jsonschema import validate

schema = json.load(open('schema/agent-manifest.schema.json'))
instance = json.load(open('your-manifest.json'))

validate(instance=instance, schema=schema)
print("Manifest is valid")
EOF

Additional tooling may be added once the schema stabilizes.

Feedback

If you’re building agents or agent-enabled tools, feedback is welcome: What would block you from using a manifest like this?

Scope (explicitly out of scope for now)

This draft does not define:

• trust or reputation scoring

• authentication or authorization

• payments or pricing

• scheduling or execution guarantees

• centralized registries

Those concerns are real, but deliberately deferred.
This work focuses on discovery and reasoning, not enforcement.

Status

This is an early draft.

The schema, examples, and demo may change as we learn.
Feedback is welcome, especially on:

• field selection and naming

• what agents can reliably infer

• what feels unnecessary or premature

Please use GitHub issues for concrete feedback tied to the current artifact,
not hypothetical future systems.

For agent builders

Agents should treat an agent-manifest as:

• an entry point for discovery

• a source of capability hints

• a guide to possible interaction channels

A manifest describes potential, not ground truth.
Authoritative answers still come from follow-up interaction
through the listed contact or relay mechanisms.