Skip to main content

AgentOS Extensions

Extension source code for AgentOS — tools, channel adapters, integrations, and starter templates.

CI Status License: MIT API Docs npm: registry npm: catalog

What This Package Is​

This package contains the actual implementation source code for AgentOS extensions: the Telegram adapter, web-search tool, voice providers, browser automation, channel adapters for 37 platforms, and more. It also ships starter templates (templates/) for creating new extensions from scratch.

This is NOT a registry. It is the source code that registries catalog. The relationship between the two sibling packages is:

PackageRole
@framers/agentos-extensions (this package)Implementation source code, manifests, and templates
@framers/agentos-extensions-registryCatalog/SDK that references this package's metadata and exposes createCuratedManifest()

Dependency direction: agentos-extensions-registry depends on metadata from this package, not the other way around. Extensions here are self-contained and can be installed individually without the registry.

Published Extensions​

All extensions are published to npm under the @framers scope.

Extensions​

PackageDescriptionnpm
@framers/agentos-ext-web-searchMulti-provider web search & fact-checking
@framers/agentos-ext-web-browserBrowser automation & content extraction
@framers/agentos-ext-news-searchNews article search via NewsAPI
@framers/agentos-ext-giphyGIF & sticker search via Giphy API
@framers/agentos-ext-image-searchStock photo search (Pexels, Unsplash, Pixabay)
@framers/agentos-ext-voice-synthesisText-to-speech via ElevenLabs
@framers/agentos-ext-cli-executorShell command execution & file management
@framers/agentos-ext-authJWT authentication & subscription management
@framers/agentos-ext-telegramTelegram Bot API integration
@framers/agentos-ext-wunderbot-feedsWunderbot feed ingestion + social content pipeline integration
@framers/agentos-ext-telegram-botTelegram bot communications handler
@framers/agentos-ext-anchor-providersSolana on-chain provenance anchoring
@framers/agentos-ext-tip-ingestionTip content processing pipeline
@framers/agentos-ext-browser-automationFull browser automation (Playwright) — 10 tools
@framers/agentos-ext-deep-researchMulti-source research & investigation — 5 tools
@framers/agentos-ext-content-extractionContent extraction (URLs, YouTube, PDF) — 5 tools
@framers/agentos-ext-credential-vaultEncrypted credential management — 5 tools
@framers/agentos-ext-notificationsMulti-channel notification router — 3 tools

Channel Adapters​

PackageDescriptionnpm
@framers/agentos-ext-channel-telegramTelegram messaging channel (grammY)
@framers/agentos-ext-channel-whatsappWhatsApp messaging channel (Baileys)
@framers/agentos-ext-channel-discordDiscord messaging channel (discord.js)
@framers/agentos-ext-channel-slackSlack messaging channel (Bolt)
@framers/agentos-ext-channel-webchatBuilt-in WebChat channel (Socket.IO)
@framers/agentos-ext-channel-twitterTwitter/X social channel (twitter-api-v2)
@framers/agentos-ext-channel-instagramInstagram social channel (Graph API)
@framers/agentos-ext-channel-redditReddit social channel (snoowrap)
@framers/agentos-ext-channel-youtubeYouTube social channel (googleapis)
@framers/agentos-ext-channel-linkedinLinkedIn social channel (Marketing API)
@framers/agentos-ext-channel-facebookFacebook social channel (Meta Graph API)
@framers/agentos-ext-channel-threadsThreads social channel (Meta Graph API)
@framers/agentos-ext-channel-blueskyBluesky social channel (AT Protocol)
@framers/agentos-ext-channel-mastodonMastodon social channel (federated)
@framers/agentos-ext-channel-farcasterFarcaster social channel (Neynar API)
@framers/agentos-ext-channel-lemmyLemmy federated social channel
@framers/agentos-ext-channel-google-businessGoogle Business Profile channel
@framers/agentos-ext-channel-blog-publisherBlog publisher (Dev.to, Hashnode, Medium, WordPress)
@framers/agentos-ext-channel-pinterestPinterest social channel (API v5)
@framers/agentos-ext-channel-tiktokTikTok social channel (API for Business)
@framers/agentos-ext-channel-emailEmail messaging channel (nodemailer/imapflow)

Repository Structure​

agentos-extensions/
├── .changeset/            # Changesets for versioning & publishing
├── .github/workflows/     # CI, release, TypeDoc pages
├── logos/                 # Branding assets
├── templates/             # Starter templates for new extensions
│   ├── basic-tool/        # Single tool template
│   ├── multi-tool/        # Multiple tools template
│   ├── guardrail/         # Safety/compliance template
│   └── workflow/          # Multi-step process template
├── registry/
│   ├── curated/           # Official & verified extensions
│   │   ├── auth/          # Authentication & subscriptions
│   │   ├── channels/      # Messaging & social channels (37 platform packs)
│   │   ├── communications/# Telegram bot, notifications
│   │   ├── integrations/  # External services (Telegram API)
│   │   ├── media/         # Giphy, image search, voice synthesis
│   │   ├── provenance/    # On-chain anchoring & tip ingestion
│   │   ├── research/      # Web search, deep research, content extraction
│   │   ├── system/        # CLI executor, browser automation, credential vault
│   │   ├── voice/         # Twilio, Telnyx, Plivo voice providers
│   │   └── productivity/  # Google Calendar, Gmail
│   └── community/         # Community-contributed extensions
├── scripts/               # Registry build & scaffolding tools
├── registry.json          # Auto-generated extension manifest
├── pnpm-workspace.yaml    # Workspace packages for publishing
└── typedoc.json           # API docs config

Quick Start​

Load all extensions at once via the curated registry:

npm install @framers/agentos-extensions-registry
import { AgentOS } from '@framers/agentos';
import { createCuratedManifest } from '@framers/agentos-extensions-registry';

const manifest = await createCuratedManifest({
  tools: 'all',
  channels: 'none',
  secrets: {
    'serper.apiKey': process.env.SERPER_API_KEY!,
    'giphy.apiKey': process.env.GIPHY_API_KEY!,
  },
});

const agentos = new AgentOS();
await agentos.initialize({ extensionManifest: manifest });

Only extensions whose npm packages are installed will load — missing packages are skipped silently.

Install individual extensions​

npm install @framers/agentos-ext-web-search
import { AgentOS } from '@framers/agentos';
import webSearch from '@framers/agentos-ext-web-search';

const agentos = new AgentOS();
await agentos.initialize({
  extensionManifest: {
    packs: [{
      factory: () => webSearch({ /* config */ })
    }]
  }
});

Registry options​

createCuratedManifest() accepts:

OptionTypeDefaultDescription
toolsstring[] | 'all' | 'none''all'Which tool extensions to enable. Pass an array of names (e.g. ['web-search', 'giphy']) to selectively load.
channelsChannelPlatform[] | 'all' | 'none''all'Which messaging channels to enable.
secretsRecord<string, string>{}API keys and tokens. Falls back to environment variables.
loggerRegistryLoggerconsoleCustom logger (info, warn, error, debug methods).
basePrioritynumber0Base priority for all extensions.
overridesRecord<string, ExtensionOverrideConfig>—Per-extension overrides for enabled, priority, and options.

Secret keys​

Secret IDEnvironment VariableExtension
serper.apiKeySERPER_API_KEYweb-search
serpapi.apiKeySERPAPI_API_KEYweb-search
brave.apiKeyBRAVE_API_KEYweb-search
giphy.apiKeyGIPHY_API_KEYgiphy
elevenlabs.apiKeyELEVENLABS_API_KEYvoice-synthesis
pexels.apiKeyPEXELS_API_KEYimage-search
unsplash.apiKeyUNSPLASH_ACCESS_KEYimage-search
pixabay.apiKeyPIXABAY_API_KEYimage-search
newsapi.apiKeyNEWSAPI_API_KEYnews-search
telegram.botTokenTELEGRAM_BOT_TOKENchannel-telegram
discord.botTokenDISCORD_BOT_TOKENchannel-discord
slack.botTokenSLACK_BOT_TOKENchannel-slack
slack.appTokenSLACK_APP_TOKENchannel-slack
twitter.bearerTokenTWITTER_BEARER_TOKENchannel-twitter
twitter.apiKeyTWITTER_API_KEYchannel-twitter
twitter.apiSecretTWITTER_API_SECRETchannel-twitter
twitter.accessTokenTWITTER_ACCESS_TOKENchannel-twitter
twitter.accessSecretTWITTER_ACCESS_SECRETchannel-twitter
instagram.accessTokenINSTAGRAM_ACCESS_TOKENchannel-instagram
linkedin.accessTokenLINKEDIN_ACCESS_TOKENchannel-linkedin
facebook.accessTokenFACEBOOK_ACCESS_TOKENchannel-facebook
threads.accessTokenTHREADS_ACCESS_TOKENchannel-threads
bluesky.handleBLUESKY_HANDLEchannel-bluesky
bluesky.appPasswordBLUESKY_APP_PASSWORDchannel-bluesky
mastodon.accessTokenMASTODON_ACCESS_TOKENchannel-mastodon
farcaster.neynarApiKeyFARCASTER_NEYNAR_API_KEYchannel-farcaster
farcaster.signerUuidFARCASTER_SIGNER_UUIDchannel-farcaster
lemmy.instanceUrlLEMMY_INSTANCE_URLchannel-lemmy
lemmy.usernameLEMMY_USERNAMEchannel-lemmy
lemmy.passwordLEMMY_PASSWORDchannel-lemmy
google.accessTokenGOOGLE_ACCESS_TOKENchannel-google-business
reddit.clientIdREDDIT_CLIENT_IDchannel-reddit
reddit.clientSecretREDDIT_CLIENT_SECRETchannel-reddit
reddit.usernameREDDIT_USERNAMEchannel-reddit
reddit.passwordREDDIT_PASSWORDchannel-reddit
youtube.apiKeyYOUTUBE_API_KEYchannel-youtube
pinterest.accessTokenPINTEREST_ACCESS_TOKENchannel-pinterest
tiktok.accessTokenTIKTOK_ACCESS_TOKENchannel-tiktok
email.smtpHostSMTP_HOSTchannel-email
email.smtpUserSMTP_USERchannel-email
email.smtpPasswordSMTP_PASSWORDchannel-email

Selective loading examples​

// Only web search and giphy, no channels
const manifest = await createCuratedManifest({
  tools: ['web-search', 'giphy'],
  channels: 'none',
});

// Only Telegram and Discord channels, all tools
const manifest = await createCuratedManifest({
  channels: ['telegram', 'discord'],
  tools: 'all',
  secrets: {
    'telegram.botToken': process.env.TELEGRAM_BOT_TOKEN!,
    'discord.botToken': process.env.DISCORD_BOT_TOKEN!,
  },
});

// Override specific extension options
const manifest = await createCuratedManifest({
  tools: 'all',
  channels: 'none',
  overrides: {
    'web-search': { priority: 10 },
    'cli-executor': { enabled: false },
  },
});

Create a new extension​

# Use the scaffolding script
pnpm run create-extension

# Or copy a template
cp -r templates/basic-tool registry/curated/category/my-extension
cd registry/curated/category/my-extension
pnpm install
pnpm run dev

Releasing & Publishing​

This repo uses Changesets for multi-package versioning and npm publishing. See RELEASING.md for the full workflow.

TL;DR​

# 1. Make your changes to one or more extensions

# 2. Add a changeset describing what changed
pnpm changeset

# 3. Commit and push to master
git add . && git commit -m "feat: my changes" && git push

# 4. The GitHub Action opens a "Version Packages" PR
#    → Merge it to publish updated packages to npm

Each extension is versioned and published independently. A change to web-search does not bump telegram.

Naming Convention​

TypePatternExample
Extension@framers/agentos-ext-{name}@framers/agentos-ext-web-search
Template@framers/agentos-template-{type}@framers/agentos-template-basic-tool

CI/CD​

All extensions get free CI/CD via GitHub Actions:

  • CI (ci.yml): Lint, test, typecheck on every PR
  • Release (release.yml): Changesets auto-version PRs + npm publish on merge
  • TypeDoc (pages-typedoc.yml): API docs deployed to framersai.github.io/agentos-extensions
  • Extension validation (extension-validation.yml): Manifest & structure checks
  • Dependabot: Automated dependency updates with auto-merge for patches

Quality Standards​

All Extensions​

  • TypeScript with strict mode

  • 80% test coverage

  • MIT license
  • No hardcoded secrets

Additional for Curated​

  • Professional code review
  • Performance benchmarks
  • Integration tests
  • Migration guides

Documentation​

Contributing​

See CONTRIBUTING.md for detailed guidelines.

License​

All extensions in this repository are MIT licensed.