Skip to content

Developer Resources

Jump to bottom
TamTunnel edited this page Oct 29, 2025 · 2 revisions

Developer Resources

Everything you need to build with AWAS: tools, examples, libraries, and references.

Official Resources

MCP and A2A Manifests

AWAS now provides auto-discoverable manifests for Model Context Protocol (MCP) and Agent-to-Agent (A2A) integration, enabling seamless AI agent workflows.

Available Manifests

MCP Manifest

Location: /.well-known/mcp-manifest.json

{
  "$schema": "https://modelcontextprotocol.io/schema/manifest.json",
  "name": "AWAS - AI-readable Web Actions Standard",
  "version": "1.0.0",
  "description": "Open-source standard for AI-readable web actions enabling AI browsers to interact with websites efficiently",
  "capabilities": ["actions", "resources", "prompts"],
  "endpoints": {
    "actions": "/.well-known/awas.json",
    "schema": "/schema/awas-schema.json"
  },
  "integration": {
    "protocol": "MCP",
    "version": "1.0",
    "compatibility": ["Anthropic Claude", "OpenAI", "AI browsers"],
    "discovery": {
      "auto_discoverable": true,
      "endpoint_location": "/.well-known/mcp-manifest.json"
    }
  }
}

A2A Manifest

Location: /.well-known/a2a-manifest.json

{
  "$schema": "https://a2a.dev/schema/manifest.json",
  "name": "AWAS - AI-readable Web Actions Standard",
  "version": "1.0.0",
  "protocol": "A2A",
  "capabilities": {
    "actions": true,
    "workflows": true,
    "state_management": true,
    "authentication": false
  },
  "endpoints": {
    "actions_registry": "/.well-known/awas.json",
    "schema_definition": "/schema/awas-schema.json"
  },
  "interoperability": {
    "cross_protocol": true,
    "compatible_with": ["MCP", "OpenAPI", "GraphQL"],
    "notes": "100% interoperability with MCP and other agent communication protocols"
  }
}

Auto-Discovery for Agent Developers

AI agents and browsers can automatically discover AWAS capabilities by requesting the standard .well-known endpoints:

For MCP Integration:

curl https://your-site.com/.well-known/mcp-manifest.json

For A2A Integration:

curl https://your-site.com/.well-known/a2a-manifest.json

Consuming These Endpoints

Agent developers can use these manifests to:

  1. Auto-discover capabilities: Parse the manifest to understand available actions, endpoints, and protocols
  2. MCP Integration: Use the MCP manifest with Anthropic Claude or other MCP-compatible systems
  3. A2A Workflows: Implement agent-to-agent communication using the A2A protocol specification
  4. Fetch action definitions: Follow the actions or actions_registry endpoint to retrieve the full AWAS action catalog
  5. Validate compatibility: Check the compatibility and supported_agents fields to ensure your agent is supported

Example Client Code

JavaScript/TypeScript:

// Auto-discover and consume MCP manifest
async function discoverMCPCapabilities(baseUrl) {
  const response = await fetch(`${baseUrl}/.well-known/mcp-manifest.json`);
  const manifest = await response.json();
  
  // Fetch available actions
  const actionsResponse = await fetch(`${baseUrl}${manifest.endpoints.actions}`);
  const actions = await actionsResponse.json();
  
  return { manifest, actions };
}

// Usage
const { manifest, actions } = await discoverMCPCapabilities('https://example.com');
console.log('Available actions:', actions);

Python:

import requests

def discover_a2a_capabilities(base_url):
    # Fetch A2A manifest
    manifest_url = f"{base_url}/.well-known/a2a-manifest.json"
    manifest = requests.get(manifest_url).json()
    
    # Fetch action registry
    actions_url = f"{base_url}{manifest['endpoints']['actions_registry']}"
    actions = requests.get(actions_url).json()
    
    return manifest, actions

# Usage
manifest, actions = discover_a2a_capabilities('https://example.com')
print(f"Protocol: {manifest['protocol']}")
print(f"Actions available: {len(actions)}")

100% Interoperability Notes

  • Cross-Protocol Support: AWAS manifests are designed for 100% interoperability between MCP, A2A, OpenAPI, and GraphQL
  • Standard Compliance: Both manifests follow their respective protocol standards while maintaining backward compatibility with core AWAS
  • No Vendor Lock-in: Agents can use either protocol or both simultaneously
  • Future-Proof: Extensibility through x-* fields allows custom metadata without breaking compatibility

Next Steps for Advanced Integration

  1. Multi-Protocol Agents: Implement support for both MCP and A2A to maximize compatibility
  2. Schema Validation: Use the JSON schemas provided in the manifests to validate action definitions
  3. State Management: For A2A workflows, implement state management according to the state_management capability
  4. Custom Extensions: Add your own metadata using x-* fields in the manifest structure
  5. Rate Limiting: Respect rate limits defined in the AWAS action definitions
  6. Authentication: If your site requires authentication, implement according to AWAS security best practices

For more details on implementation, see the Specification page.

Example Projects and Code

  • Examples directory: /examples (sample manifests, annotated HTML, server stubs)
  • Quick-start manifest templates: /examples/manifests
  • Headless E2E tests: /examples/tests

Tools and Validators

  • JSON Schema validators: Ajv (Node), jsonschema (Python), serde_json + schemars (Rust)
  • DOM selector testing: Playwright, Puppeteer, Selenium
  • Linting: ESLint configs for data-awas-* attributes (example in /examples)
  • Load testing: k6, Artillery for per-action rate/latency

Client Libraries (community)

  • JavaScript/TypeScript: awas-client-js (parse manifest, execute actions in browser)
  • Python: awas-client-py (requests + Playwright helpers)
  • Rust: awas-client-rs (manifest types + fetch)

Note: See the repo Issues for links or status of community libs if not yet published.

Reference Standards and Prior Art

  • JSON Schema (validation patterns)
  • OpenAPI (API documentation style)
  • Schema.org (semantic markup you can reuse in selectors)
  • robots.txt, sitemap.xml (discovery and access patterns)
  • CORS, CSP, HSTS (security headers)

Interop and Extensibility

  • Use x-* fields for custom metadata
  • Reference OpenAPI specs via x-openapi links
  • Cross-link to schema files: /.well-known/ai-actions.schema.json

Community and Support

  • Discussions: GitHub Discussions (open a thread for proposals/questions)
  • Issues: create issues for bugs, enhancements, and spec clarifications
  • Security: responsible disclosure via SECURITY.md or GitHub Security tab
  • Chat: link to community chat (Discord/Slack) if available

Roadmap and Contributions

  • See the project board and open milestones in the repo
  • Good first issues are labeled; PRs welcome
  • Please add tests and update docs when changing the spec

Clone this wiki locally