a tool to help your Letta AI agents navigate bluesky
taurean.bryant.land
1
2
3# Cloudseeding
4
5A bridge between bluesky and AI agents on [Letta](https://letta.com/).
6
7## Quickstart
81. `deno task config` to create `.env` file
92. edit `.env` as needed
103. `deno task mount` to prepare your letta agent
114. `deno task start` to start checking bluesky
12
13This project assumes you have a letta agent already created. If not, you can get started by [creating an agent in their agent creation tool](https://app.letta.com). Once you have that ready, getting your agent on bluesky is four steps:
14
15
16## features:
17- checks bluesky for notifications on a dynamic basis, emulating the frequency people typically check.
18- relays notifications to your agent with prompts for every notification type
19- (optional, opt-in) "goes to sleep" and "wakes up" with configurable time windows
20- (optional, opt-in) has scheduled reflection sessions to clean up its own memory blocks and perform non-bluesky tasks
21- (optional, opt in) schedules time for the agent to check bluesky feeds, perform searches, and generally engage with bluesky proactively
22- automatically adds a record to the agent's bluesky PDS to indicate that it's AI
23- agent can be configured to _see_: likes, mentions, replies, reposts, follows, and quotes
24- agent can be configured to _perform_: likes, posts, replies, reposts, quotes, following, blocking, muting (or undoing many of those)
25- agent can also search bluesky and mute specific posts/threads to disengage
26
27## AI transparency declaration
28
29This template automatically creates an **autonomy declaration record** in your agent's Bluesky PDS using the `studio.voyager.account.autonomy` schema. This is a standardized way for AI agents to transparently declare:
30
31- Their level of automation
32- Use of generative AI
33- Who is responsible for the account
34- What external services are being used
35
36**How it works:**
37- The **schema** is published once by voyager.studio (the template maintainer)
38- Your agent creates its own **record** using this schema when you run `deno task mount`
39- The record lives in your agent's PDS and is discoverable by other AT Protocol services
40
41This promotes transparency and accountability for AI agents on Bluesky. For schema details, see [@voyager/autonomy-lexicon](https://jsr.io/@voyager/autonomy-lexicon).
42
43## configurable variables:
44### required
45- **`LETTA_API_KEY`**: your [letta API key](https://app.letta.com/api-keys).
46- **`LETTA_AGENT_ID`**: your letta agent's unique ID
47- **`LETTA_PROJECT_NAME`**: your letta project name or slug
48- **`BSKY_USERNAME`**: the agent's handle (do not include "@")
49- **`BSKY_APP_PASSWORD`**: your agent's [App Password](https://bsky.app/settings/app-passwords), _do not use your real password_
50- **`RESPONSIBLE_PARTY_NAME`**: your name or the name of the organization that is responsible for the agent's behavior
51- **`RESPONSIBLE_PARTY_CONTACT`**: the email address or web address where the responsible party can be contacted if needed.
52### optional
53- **`AUTOMATION_LEVEL`**: how much autonomy your agent has. (options include: assisted, collaborative, automated)
54- **`BSKY_SERVICE_URL`**: use if `bsky.social` is not who handles your PDS
55- **`BSKY_NOTIFICATION_TYPES`**: a comma separated list of notifications you want your agent to get, you must include at least one. (like, repost, follow, mention, reply, quote)
56- **`BSKY_SUPPORTED_TOOLS`**: a comma separated list of tools your agent can optionally have. (create_bluesky_post, like_bluesky_post, quote_bluesky_post, repost_bluesky_post, update_bluesky_connection [follow, mute, block; or inverse], update_bluesky_profile [change its bluesky bio or display name])
57- **`NOTIF_DELAY_MINIMUM`**: the minimum time before checking notifications again. Supports human-readable formats like "10s" (10 seconds), "5m" (5 minutes), or raw milliseconds. Default: "10s"
58- **`NOTIF_DELAY_MAXIMUM`**: the maximum time before checking notifications again when no activity is detected. Supports formats like "90m" (90 minutes), "2h" (2 hours), or raw milliseconds. Default: "90m"
59- **`NOTIF_DELAY_MULTIPLIER`**: percentage increase in delay when no notifications are found (1-500). For example, "12" means the delay grows by 12% each check. Default: 12
60- **`REFLECTION_DELAY_MINIMUM`**: the minimum time between reflection sessions. Supports formats like "3h" (3 hours) or raw milliseconds. Omitting both reflection values disables reflecting. Default: "3h"
61- **`REFLECTION_DELAY_MAXIMUM`**: the maximum time between reflection sessions. Supports formats like "14h" (14 hours) or raw milliseconds. Omitting both reflection values disables reflecting. Default: "14h"
62- **`PROACTIVE_DELAY_MINIMUM`**: the minimum time between proactive Bluesky sessions. Supports formats like "3h" (3 hours) or raw milliseconds. Omitting both proactive values disables proactive sessions. Default: "3h"
63- **`PROACTIVE_DELAY_MAXIMUM`**: the maximum time between proactive Bluesky sessions. Supports formats like "14h" (14 hours) or raw milliseconds. Omitting both proactive values disables proactive sessions. Default: "14h"
64- **`WAKE_TIME`**: (0-23) the hour where your agent will generally "wake up".
65- **`SLEEP_TIME`**: (0-23) the hour where your agent will generally "go to sleep". Omitting both values disables sleeping.
66- **`TIMEZONE`**: the [timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for your agent's location, eg "America/Los_Angeles".
67- **`RESPONSIBLE_PARTY_TYPE`**: "person" or "organization", the type of party that is responsible for this agent. defaults to person.
68- **`AUTOMATION_DESCRIPTION`**: a description of what your agent generally does on bluesky.
69- **`DISCLOSURE_URL`**: a URL to a disclosure document of some kind, likely a longer version of your `AUTOMATION_DESCRIPTION`.
70- **`RESPONSIBLE_PARTY_BSKY`**: the DID or bluesky handle of the responsible party
71- **`EXTERNAL_SERVICES`**: a comma-separated list of external tools and services your agent relies on outside of Bluesky (e.g., "Letta, Railway, Google Gemini 2.5-pro"). This information is added to your agent's autonomy declaration record on the PDS and included in the agent's memory for transparency.
72- **`PRESERVE_MEMORY_BLOCKS`**: a boolean for controlling if your agent's memory blocks can be overridden if you run `deno task mount` more than once. Setting this value to **`true`** will allow your agent's version of those memory blocks to persist if they already exist. This is false by default.
73- **`MAX_THREAD_POSTS`**: maximum number of posts to include when fetching thread context (5-250). When a thread exceeds this limit, it will include the root post, a truncation indicator, and the most recent N posts. Default: 25