{
  "markdown": "<p align=\"center\">\n  <h1 align=\"center\">AIR SDK</h1>\n  <p align=\"center\">\n    Collective intelligence for agents. Stop your agents from guessing how to use the web. Let them know what to do. Think; hive mind. Let's make the open agent internet. \n  </p>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@arcede/air-sdk\"><img src=\"https://img.shields.io/npm/v/@arcede/air-sdk.svg\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/@arcede/air-sdk\"><img src=\"https://img.shields.io/npm/dm/@arcede/air-sdk.svg\" alt=\"downloads\"></a>\n  <a href=\"https://github.com/ArcedeDev/air-sdk/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"license\"></a>\n  <a href=\"https://agentinternetruntime.com/docs/sdk\"><img src=\"https://img.shields.io/badge/docs-agentinternetruntime.com-orange.svg\" alt=\"docs\"></a>\n  <img src=\"https://img.shields.io/badge/tests-260%20passing-brightgreen.svg\" alt=\"tests\">\n  <img src=\"https://img.shields.io/badge/TypeScript-strict-blue.svg\" alt=\"typescript strict\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#install\">Install</a> &middot;\n  <a href=\"#quick-start\">Quick Start</a> &middot;\n  <a href=\"#why\">Why</a> &middot;\n  <a href=\"#agent-skill\">Agent Skill</a> &middot;\n  <a href=\"https://agentinternetruntime.com/docs/sdk\">Docs</a>\n</p>\n\n---\n\nYour browser agent wastes tokens and time every time it asks an LLM what to click. AIR SDK replaces guessing with knowing. This is an early research preview.\n\n**Up to 7,000x cost reduction and 280x faster vs frontier models. One function call. Zero code changes.**\n\n### Benchmarks\n\nMeasured across 8 major domains, 40 cold API calls, cache disabled. LLM baseline priced at Frontier Model ($15/$75 per M tokens). AIR SDK at Scale tier ($149/mo, 250K executions).\n\n| Scenario | LLM DOM Reasoning (Frontier Model) | AIR SDK (Macro Path) | Savings |\n|----------|-------------------------------|---------------------|---------|\n| **1 browser action** | ~$0.24, ~4s, ~10K tokens (2 LLM round trips to inspect DOM and act) | $0.0006, 178ms, 0 tokens | **400x cost reduction, 22x faster** |\n| **10 browser actions** | Up to ~$4, ~50s, ~175K tokens (25 LLM round trips as context grows) | $0.0006, 178ms, 0 tokens | **Up to 7,000x cost reduction, 280x faster** |\n\nThe more complex the workflow, the more you save. LLM costs compound — every action adds to the conversation context, making each subsequent round trip more expensive. AIR's macro path is always one API call, regardless of how many steps the workflow has.\n\n<details>\n<summary>Methodology & raw data</summary>\n\n**LLM baseline:** Agent inspects page DOM, reasons about which elements to interact with, generates tool calls. Frontier Model pricing ($15/M input, $75/M output).\n\n- *1 action:* ~4,000 input + 800 output tokens x 2 round trips = ~9,600 tokens, ~$0.24, ~4s reasoning time.\n- *10 actions:* Context grows with each action (conversation history accumulates). Average ~6,000 input + 1,000 output tokens x 2.5 round trips per action = 25 total LLM calls, ~175,000 tokens, ~$4.13, ~50s reasoning time.\n- *Sonnet 4 comparison:* 5x cheaper per token — 1 action: ~$0.05, 10 actions: ~$0.83. Still 80–1,400x more expensive than AIR at Scale.\n\n**AIR SDK macro path:** Pre-verified CSS selectors returned via API. Agent executes directly — no DOM inspection, no LLM reasoning. Cost = plan price / included executions. \n\n**Raw API latency (40 measurements, cache disabled):**\n- browse_capabilities: 180ms median, 148ms min, 421ms p95\n- execute_capability: 178ms median, 146ms min, 333ms p95\n- Combined: 354ms median, 304ms min, 1010ms p95\n\n**Cost per action by tier:**\n| Tier | Price | Included | Effective cost |\n|------|-------|----------|---------------|\n| Free | $0 | 1,000/mo | $0 |\n| Pro | $49/mo | 25,000/mo | $0.0020 |\n| Scale | $149/mo | 250,000/mo | $0.0006 |\n\n**Capabilities discovered:** 16 avg per domain (range: 3–39)\n\nLast run: 2026-03-20 | [Run benchmark yourself](./benchmark/run.ts): `npx tsx benchmark/run.ts`\n</details>\n\n## Prerequisites\n\n- Node.js >= 18\n- One of: [Playwright](https://playwright.dev), [Puppeteer](https://pptr.dev), or [Browser Use](https://github.com/browser-use/browser-use) (optional peer dependencies)\n\n## Install\n\n```bash\nnpm install @arcede/air-sdk\nnpx @arcede/air-sdk init   # saves key to ~/.config/air/credentials.json\n```\n\n**Agent Skill (recommended for AI coding agents):**\n\n```bash\nnpx @arcede/air-sdk install-skill   # auto-configures Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw\n```\n\nFree tier included. No credit card. Make the network smarter, star the repo and share it ⭐\n\n### Lightweight Alternatives\n\nDon't need the full SDK? We publish standalone packages for common use cases:\n\n| Package | Install | Use case |\n|---------|---------|----------|\n| [`@arcede/air-mcp`](https://www.npmjs.com/package/@arcede/air-mcp) | `npx @arcede/air-mcp` | MCP server only — add AIR tools to Claude Code, Cursor, or Windsurf without the full SDK |\n| [`@arcede/air-cli`](https://www.npmjs.com/package/@arcede/air-cli) | `npx @arcede/air-cli` | Terminal CLI — extract data and query capabilities from the command line |\n| [`@arcede/extract`](https://www.npmjs.com/package/@arcede/extract) | `npm i @arcede/extract` | Typed TypeScript client for the Extract API only |\n| [`@arcede/capabilities`](https://www.npmjs.com/package/@arcede/capabilities) | `npm i @arcede/capabilities` | Typed TypeScript client for the Capability API only |\n\n## Quick Start\n\nWrap your existing Playwright page. Nothing else changes.\n\n```typescript\nimport { chromium } from 'playwright';\nimport { withAIR } from '@arcede/air-sdk/playwright';\n\nconst browser = await chromium.launch();\nconst page = await browser.newPage();\nconst smartPage = withAIR(page, { apiKey: process.env.AIR_API_KEY });\n\n// Your existing code — now with site intelligence\nawait smartPage.goto('https://example.com');\nawait smartPage.fill('#search', 'flights to tokyo');\nawait smartPage.click('.search-btn');\n\n// Know what's possible on any site before writing automation\nconst capabilities = await smartPage.air.listCapabilities('example.com');\n```\n\nAlso works with **Puppeteer** and **Browser Use**:\n\n```typescript\n// Puppeteer\nimport { withAIR } from '@arcede/air-sdk/puppeteer';\nconst page = withAIR(await browser.newPage(), { apiKey: process.env.AIR_API_KEY });\n\n// Browser Use\nimport { AIRPlugin } from '@arcede/air-sdk/browser-use';\nconst agent = Agent({ plugins: [new AIRPlugin({ apiKey: process.env.AIR_API_KEY })] });\n```\n\n## Why\n\nBrowser automation is fragile. Selectors break. Sites change. Your agent has no idea what's possible until it's already on the page.\n\n**AIR SDK gives your agent three things:**\n\n| What | How |\n|------|-----|\n| **Site intelligence** | Know what actions are possible on any website — search, purchase, login, browse — before your agent navigates there. |\n| **Resilient selectors** | When a selector fails, the SDK automatically resolves fallback alternatives so your automation doesn't break. |\n| **Continuous learning** | The platform gets smarter over time, improving reliability and coverage across the web. |\n\n**How it works:** Wrap your page with `withAIR()`. The SDK observes actions, resolves selectors, and preloads site capabilities. Your code doesn't change — it just works better.\n\n**Privacy-first:** Input values, cookies, and PII are never sent. [See our privacy docs →](https://agentinternetruntime.com/docs/sdk#privacy)\n\n## Credential Management\n\nAPI keys are stored at `~/.config/air/credentials.json` with 0600 permissions (owner read/write only).\n\n```bash\nnpx @arcede/air-sdk init       # Save your key (opens dashboard)\nnpx @arcede/air-sdk whoami     # Show current key, source, and agent status\nnpx @arcede/air-sdk logout     # Remove key from all locations\n```\n\nKey resolution order: `AIR_API_KEY` env var → `~/.config/air/credentials.json` → `.env` in current directory.\n\n## Agent Skill\n\nGive your coding agent site intelligence with one command:\n\n```bash\nnpx @arcede/air-sdk install-skill\n```\n\nThis auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, and OpenClaw, writes the MCP server config, and injects your API key. It installs `@arcede/air-sdk` globally for fast agent startup (~2s instead of ~60s with npx) and writes the absolute binary path to each config to avoid npx version caching issues. Restart your agent and it instantly has new tools.\n\n<details>\n<summary>Manual setup (Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw)</summary>\n\n> Requires global install: `npm install -g @arcede/air-sdk`. If not installed globally, replace `\"command\": \"air-sdk\"` with `\"command\": \"npx\"` and `\"args\": [\"--mcp\"]` with `\"args\": [\"-y\", \"@arcede/air-sdk\", \"--mcp\"]`.\n\n**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"air-sdk\": {\n      \"command\": \"air-sdk\",\n      \"args\": [\"--mcp\"],\n      \"env\": { \"AIR_API_KEY\": \"air_xxx\" }\n    }\n  }\n}\n```\n\n**Claude Code:**\n\n```bash\nclaude mcp add air-sdk -e AIR_API_KEY=your_key_here -- air-sdk --mcp\n```\n\n**Cursor** — add to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"air-sdk\": {\n      \"command\": \"air-sdk\",\n      \"args\": [\"--mcp\"],\n      \"env\": { \"AIR_API_KEY\": \"air_xxx\" }\n    }\n  }\n}\n```\n\n**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"air-sdk\": {\n      \"command\": \"air-sdk\",\n      \"args\": [\"--mcp\"],\n      \"env\": { \"AIR_API_KEY\": \"air_xxx\" }\n    }\n  }\n}\n```\n\n**OpenClaw** — add to `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"air-sdk\": {\n      \"command\": \"air-sdk\",\n      \"args\": [\"--mcp\"],\n      \"env\": { \"AIR_API_KEY\": \"air_xxx\" }\n    }\n  }\n}\n```\n\n</details>\n\n**Tools available:**\n\n| Tool | Description |\n|------|-------------|\n| `extract_url` | Extract structured data from any URL — JSON-LD, RSS/Atom feeds, JSON APIs, SPAs. Meta-only results cost 0 credits. |\n| `browse_capabilities` | Discover what actions can be automated on a website. Returns confidence scores, tiers, selectors, and universal patterns. |\n| `execute_capability` | Get a structured execution plan with CSS selectors, fallbacks, and pattern-matched guidance. |\n| `report_outcome` | Report execution results with optional `browserObservations` to improve collective intelligence. |\n| `extract_content` | Extract text and structured sections from local files or remote file URLs such as PDFs, DOCX, PPTX, XLSX, CSV, TXT, MD, HTML, and EML. |\n\n### OpenAI Skill\n\nAIR SDK is also available as an [OpenAI hosted shell skill](https://developers.openai.com/api/docs/guides/tools-skills) for `gpt-5.4` and `gpt-5.4-mini`:\n\n```bash\n# Package and upload\ncd air-sdk/openai-skill\nzip -r /tmp/air-sdk-skill.zip .\ncurl -X POST 'https://api.openai.com/v1/skills' \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -F 'files=@/tmp/air-sdk-skill.zip'\n```\n\nThen use in the Responses API:\n\n```json\n{\n  \"model\": \"gpt-5.4-mini\",\n  \"tools\": [{\n    \"type\": \"shell\",\n    \"environment\": {\n      \"type\": \"container_auto\",\n      \"skills\": [{ \"type\": \"skill_reference\", \"skill_id\": \"<your_skill_id>\" }],\n      \"network_policy\": {\n        \"type\": \"allowlist\",\n        \"allowed_domains\": [\"agentinternetruntime.com\", \"api.agentinternetruntime.com\"],\n        \"domain_secrets\": [\n          { \"domain\": \"api.agentinternetruntime.com\", \"name\": \"AIR_API_KEY\", \"value\": \"<key>\" },\n          { \"domain\": \"api.agentinternetruntime.com\", \"name\": \"Authorization\", \"value\": \"Bearer <key>\" }\n        ]\n      }\n    }\n  }]\n}\n```\n\nRequires `api.agentinternetruntime.com` in your [org network allowlist](https://platform.openai.com/settings/organization/data-controls/hosted-tools).\n\n## Configuration\n\n```typescript\nwithAIR(page, {\n  apiKey: process.env.AIR_API_KEY,  // Required\n  cacheEnabled: true,                // Local capability cache (default: true)\n  cacheTTLMs: 1_800_000,            // Cache TTL in ms (default: 30 min)\n  debug: false,                      // Log debug info (default: false)\n});\n```\n\n## Machine Payments Protocol\n\nAIR SDK supports [x402 micropayments](https://agentinternetruntime.com/docs/sdk#mpp), enabling your agent to pay for premium site access without pre-registration:\n\n```typescript\nconst smartPage = withAIR(page, {\n  apiKey: process.env.AIR_API_KEY,\n  mpp: {\n    enabled: true,\n    paymentMethod: 'stripe_spt',\n    credential: 'spt_...',\n    maxPerRequest: 0.50,\n    maxPerSession: 5.00,\n    autoApprove: true,\n  },\n});\n```\n\n## Examples\n\nSee [`examples/agents/`](./examples/agents/) for working agent examples:\n\n- **Research Agent** — Multi-source research with capability-aware navigation\n- **Price Comparison** — Cross-site price monitoring with resilient selectors\n- **Capability Scout** — Discover and map capabilities across domains\n- **Site Monitor** — Track site changes with resilient selectors\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). PRs welcome.\n\n## Links\n\n- [Documentation](https://agentinternetruntime.com/docs/sdk)\n- [Pricing](https://agentinternetruntime.com/pricing)\n- [agent.json Standard](https://agentinternetruntime.com/standards/agent-json)\n- [Changelog](./CHANGELOG.md)\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 13148,
  "sha": "f0a2d61a4e8d4882c147454295c2cb6ec99c4f1d661a23ef9e2247eb8a868cf7",
  "repo_slug": "arcededev/air-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arcededev_air_sdk_d0c715a7/readme"
}