Photon 开源 Spectrum 多渠道智能体框架

Bring agents to any interface.

Photon (photon.codes) builds Spectrum, a multi-channel agent framework that makes AI agents reachable over real conversation surfaces like iMessage, SMS, and email instead of trapping them in web chat.

About Photon

Photon builds infrastructure for AI agents that operate over real communication channels.

Spectrum is Photon’s open-source multi-channel agent framework, enabling AI agents to communicate through interfaces people already use—such as iMessage, SMS, email, Slack, Discord, and voice—instead of being confined to web chat.

Learn more at https://photon.codes.

Getting Started

The fastest way to ship is with Spectrum Cloud — hosted infrastructure for platforms like iMessage, with credentials ready in minutes.

1. Sign up at app.photon.codes to get your project ID and secret.

2. Install the SDK (spectrum-ts is batteries-included — the runtime plus the standard provider set):

   bun add spectrum-ts

3. Start your app:

   import { Spectrum } from "spectrum-ts";
   import { imessage } from "spectrum-ts/providers/imessage";
   
   const app = await Spectrum({
     projectId: process.env.PROJECT_ID,
     projectSecret: process.env.PROJECT_SECRET,
     providers: [imessage.config()],
   });
   
   for await (const [space, message] of app.messages) {
     await space.responding(async () => {
       await message.reply("Hello from Spectrum.");
     });
   }

Spectrum also runs fully standalone — you can connect to a local iMessage database with the separate @spectrum-ts/imessage-local package, bring your own gRPC endpoints, or build your own platform provider. See the docs for self-hosted setups.

Startup cancellation

Pass an AbortSignal to cancel initialization. The signal applies only until Spectrum() returns. It does not stop a successfully initialized instance.

const app = await Spectrum({
  projectId,
  projectSecret,
  providers: [imessage.config()],
  signal: AbortSignal.timeout(10_000),
});

Project lookup and cloud iMessage, WhatsApp Business, and Slack token requests use this signal through response-body reads. Telegram webhook registration also receives it. No startup deadline applies unless the caller supplies one.

If initialization fails, Spectrum destroys providers that already returned a client and awaits their cleanup before rejecting. If a provider ignores cancellation, startup still waits for that provider to settle. Cleanup that never settles also keeps startup pending. This option does not interrupt imports, Terminal startup, local iMessage startup, or the later lazy Fusor connection.

If cleanup fails, the factory throws SpectrumStartupCleanupError. Its cause is the startup error, and its errors contain the cleanup failures. Do not automatically start a replacement after this error because resources can remain active.

Provider authors receive signal in lifecycle.createClient. Pass it to startup I/O, but do not keep it for later client operations. If createClient fails before returning, the provider must clean up its own partial resources. Cloud token renewals use a separate lifetime signal, and await renewal.dispose() cancels and settles an active refresh before teardown. Later calls to forceRefresh() or refreshIfNeeded() reject after disposal. Update core and provider packages together to enable startup cancellation.

Cancellation does not prove that the server rolled back a request that it already received. It does not replay messages or change delivery guarantees.

Documentation

Visit docs.photon.codes to view the full documentation.

Platforms

bun add spectrum-ts is batteries-included (the standard provider set; local iMessage is an explicit install). For a smaller install, depend on the runtime plus only the providers you use — bun add @spectrum-ts/core @spectrum-ts/telegram — and import from the scoped packages directly. Either way the spectrum-ts/providers/<platform> import paths work as long as the matching provider package is installed; if it isn't, the import fails at build/startup naming the exact package to add.

Issues

Found a bug or have a feature request? Please open an issue on GitHub. Before filing, search existing issues to avoid duplicates.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

MIT © Photon