callable.json

An open protocol for agent-to-business capability discovery on the web.

callable.json lets any AI agent discover what a business can do — and how to interact with it — with a single HTTP request. No marketplace, no central registry, no prior integration required.

GET https://acmeauto.com/.well-known/callable.json

{
  "callable": "0.1",
  "name": "Acme Auto Service",
  "description": "Schedule and manage vehicle service appointments",
  "endpoint": "https://agents.acmeauto.com/a2a",
  "protocol": "a2a",
  "auth": {
    "type": "oauth2",
    "authorization_url": "https://auth.acmeauto.com/authorize",
    "token_url": "https://auth.acmeauto.com/token",
    "scopes": ["service:read", "service:write"]
  },
  "actions": [
    {
      "id": "service.schedule",
      "description": "Schedule a vehicle service appointment",
      "input_schema": {
        "type": "object",
        "properties": {
          "vehicle_vin": { "type": "string", "description": "Vehicle identification number" },
          "service_type": { "type": "string", "enum": ["oil_change", "tire_rotation", "brake_service", "inspection", "recall", "other"] },
          "preferred_date": { "type": "string", "format": "date" },
          "preferred_time": { "type": "string", "enum": ["morning", "afternoon", "evening"] }
        },
        "required": ["vehicle_vin", "service_type", "preferred_date"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "confirmation_number": { "type": "string" },
          "appointment_datetime": { "type": "string", "format": "date-time" },
          "location": { "type": "string" }
        }
      }
    }
  ]
}

Why

AI agents are becoming the primary way people interact with digital services. But when a user asks their agent to book a car service appointment, the agent has no way to know:

• Whether that business supports agent interactions at all
• What actions are available
• Where to send the request
• How to authenticate

Today the only options are hard-coded integrations, curated marketplaces, or brittle browser automation. None of these scale to the open web.

The web already solved analogous discovery problems with well-known paths:

Path	Purpose
/robots.txt	Crawler access rules
/.well-known/openid-configuration	OAuth/OIDC discovery
/sitemap.xml	Page discovery for search engines

callable.json applies this pattern to agent capability discovery.

How It Works

User: "Book my car in for an oil change Tuesday morning"

1. Agent  →  GET acmeauto.com/.well-known/callable.json
         ←  Capability declaration + endpoint + auth requirements

2. Agent  →  OAuth2 authorization (user grants consent)

3. Agent  →  POST agents.acmeauto.com/a2a  { action: "service.schedule", ... }
         ←  { confirmation: "SA-2041", datetime: "Apr 14 9:00 AM" }

No browser automation. No scraping. No custom integration. A sanctioned, structured transaction.

Protocol Design Principles

1. No central registry — peer-to-peer discovery via well-known paths
2. Complement existing protocols — callable.json handles discovery; A2A, MCP, or REST handle execution
3. Trust is layered — unverified → DNS-verified → PKI-verified
4. Human authorization is preserved — OAuth2 delegation means users grant explicit consent

Relation to Existing Protocols

callable.json is the discovery layer that sits in front of execution protocols:

callable.json   →  "What can this business do? Where do I send requests?"
A2A             →  Agent-to-agent task execution
MCP             →  Agent-to-tool communication

callable.json is not a replacement for A2A or MCP. It answers the question they don't: how does an agent find out what's available in the first place?

Repository Structure

├── README.md              ← You are here
├── spec/
│   ├── protocol.md        ← Protocol specification (v0.1-draft)
│   └── callable.json.schema.json  ← JSON Schema for the Callable Card
├── whitepaper.md          ← Protocol rationale and design
├── examples/
│   ├── auto-service.callable.json
│   ├── healthcare.callable.json
│   └── home-services.callable.json
├── CONTRIBUTING.md
└── LICENSE (MIT)

Quick Start

For businesses: Create a callable.json file describing your agent-facing capabilities and serve it at /.well-known/callable.json on your domain.

For agent developers: Check for /.well-known/callable.json on any domain to discover available actions, authentication requirements, and endpoints.

For platform providers: Generate and host callable.json endpoints for the businesses on your platform. One integration pattern covers all your customers.

See spec/protocol.md for the full specification.

Status

v0.1-draft — This specification is in active development. We welcome feedback via GitHub Issues and pull requests.

Contributing

See CONTRIBUTING.md for guidelines. We're especially looking for:

• Feedback on the schema design and action taxonomy
• Example Callable Cards for new verticals
• Agent implementation experience reports
• Security and privacy review

License

MIT — see LICENSE.

---

callable.json is an open protocol maintained by its community of contributors.