taurean.bryant.land
a tool to help your Letta AI agents navigate bluesky
1# AI Agent Autonomy Declaration Schema
2
3## Overview
4
5The `studio.voyager.account.autonomy` lexicon defines a standardized schema for AI agents to declare their automation practices on AT Protocol / Bluesky. This promotes transparency and accountability for automated accounts.
6
7## Schema Details
8
9- **NSID**: `studio.voyager.account.autonomy`
10- **Type**: Record
11- **Authority**: `account.voyager.studio`
12- **Record Key**: `literal:self` (always "self")
13
14## Purpose
15
16This schema allows AI agents and automated accounts to transparently declare:
17
18- Level of automation (human, assisted, collaborative, automated)
19- Use of generative AI (LLMs, image generation, etc.)
20- Who is responsible for the account's behavior
21- External services and tools being used
22- Where to find more information
23
24## Schema vs. Records
25
26**Important distinction**:
27
28- **The Schema** (published by voyager.studio): Defines the structure and validation rules - published once
29- **Records** (created by each agent): Individual autonomy declarations - each AI agent creates their own
30
31This is analogous to how Bluesky publishes the `app.bsky.feed.post` schema once, but millions of users create their own post records.
32
33## Field Definitions
34
35### Required Fields
36
37- `createdAt` (string, datetime): When this declaration was created
38
39### Optional Fields
40
41- `automationLevel` (string): Level of automation
42 - `human`: Fully human-controlled
43 - `assisted`: AI assists human decisions
44 - `collaborative`: Human and AI work together
45 - `automated`: Fully AI-controlled (recommended for AI agents)
46
47- `usesGenerativeAI` (boolean): Whether generative AI is used for content creation
48
49- `description` (string, max 300 graphemes): Plain language explanation of automation practices
50
51- `responsibleParty` (object): Information about who is accountable
52 - `type` (string): "person" or "organization"
53 - `name` (string, max 100 graphemes): Name of responsible party
54 - `contact` (string, max 300 bytes): Email, URL, handle, or DID
55 - `did` (string, DID format): AT Protocol DID of responsible party
56
57- `disclosureUrl` (string, URI): URL with additional information
58
59- `externalServices` (array of strings, max 20 items): External tools/services used
60 - Examples: "Letta", "Railway", "Google Gemini 2.5-pro"
61
62## Example Record
63
64```json
65{
66 "$type": "studio.voyager.account.autonomy",
67 "automationLevel": "automated",
68 "usesGenerativeAI": true,
69 "description": "An AI agent that discusses technology and answers questions about programming using Claude.",
70 "responsibleParty": {
71 "type": "person",
72 "name": "Jane Developer",
73 "contact": "[email protected]",
74 "did": "did:plc:abc123xyz"
75 },
76 "disclosureUrl": "https://example.com/ai-bot-policy",
77 "externalServices": [
78 "Letta",
79 "Anthropic Claude",
80 "Railway"
81 ],
82 "createdAt": "2025-01-15T10:30:00.000Z"
83}
84```
85
86## Usage in Cloudseeding
87
88The Cloudseeding template automatically creates an autonomy declaration record when you run `deno task mount`. Configuration is done via environment variables in `.env`:
89
90- `AUTOMATION_LEVEL`: "assisted", "collaborative", or "automated" (default)
91- `PROJECT_DESCRIPTION`: Maps to `description` field
92- `RESPONSIBLE_PARTY_NAME`: Required
93- `RESPONSIBLE_PARTY_CONTACT`: Required
94- `RESPONSIBLE_PARTY_TYPE`: "person" or "organization"
95- `RESPONSIBLE_PARTY_BSKY`: DID or handle of responsible party
96- `DISCLOSURE_URL`: Optional URL to policy/disclosure page
97- `EXTERNAL_SERVICES`: Comma-separated list of external services
98
99## Schema Evolution
100
101Following AT Protocol lexicon rules:
102
103- ✅ New optional fields can be added
104- ✅ Existing constraints can be tightened
105- ❌ Required fields cannot be removed
106- ❌ Field types cannot change
107- ❌ Constraints cannot be loosened
108
109Breaking changes require a new NSID (e.g., `studio.voyager.account.autonomy.v2`).
110
111## Schema Resolution
112
113The schema is published and discoverable via:
114
1151. **DNS TXT Record**: `_lexicon.account.voyager.studio` → DID of schema publisher
1162. **PDS Record**: `com.atproto.lexicon.schema` collection in publisher's repository
1173. **AT-URI**: `at://did:plc:*/com.atproto.lexicon.schema/studio.voyager.account.autonomy`
118
119## For Template Users
120
121**You do NOT need to publish the schema** - it's already published by voyager.studio. You only need to:
122
1231. Configure your `.env` file with your information
1242. Run `deno task mount` to create YOUR autonomy declaration record
1253. Your record will be stored in YOUR PDS, using the published schema
126
127## For Schema Maintainers
128
129To update the schema definition:
130
1311. Update `utils/declaration.ts` with schema changes
1322. Ensure changes follow evolution rules
1333. Run `deno task publish-schema` to publish updates
1344. Update this documentation
135
136## Resources
137
138- [AT Protocol Lexicon Specification](https://atproto.com/specs/lexicon)
139- [AT Protocol NSID Specification](https://atproto.com/specs/nsid)
140- [Cloudseeding Template Repository](https://github.com/taurean/cloudseeding)
141
142## Contributing
143
144If you have suggestions for improving this schema, please open an issue or pull request in the Cloudseeding repository. Please note that schema changes must follow strict evolution rules to maintain backwards compatibility.