Prompt
Agent instructions: you write Bluesky posts for our developer tools company. Given a changelog entry, write one post under 280 graphemes with the docs link, then call draft_post with networks ["bluesky"]. Input: 'Added TypeScript types for the webhooks client. Docs: docs.example.dev/sdk/webhooks'.How to do it
- Mint a Bluesky agent key In https://app.socialhandoff.com, open Connections, connect your Bluesky account, then create an agent key scoped to Bluesky with draft permission only. Copy the key when it is shown; only its hash is stored.
- Connect the MCP server Create an MCPServerStreamableHttp with url https://app.socialhandoff.com/mcp and an Authorization: Bearer header, and open it with async with.
- Attach it to an Agent Pass it in mcp_servers when you build the Agent. Write instructions that name Bluesky, its length limit, and the draft_post tool.
- Run and trace Call Runner.run, then read the trace to see each tool call. The post id in the output points at a pending draft in the approval inbox.
Example draft
The webhooks client now ships TypeScript types. Event payloads are typed by event name, so your editor knows exactly what a payment.succeeded body contains. docs.example.dev/sdk/webhooks
Gotchas
- Links, @handles, and #tags become clickable facets when the post publishes. Have the agent write the plain URL and handle, not markdown links.
- Connect Bluesky with an app password from Settings, never your account password. Revoking that app password cuts off only this connection.
- The 300 limit counts graphemes, so an emoji or accented letter counts as one. Anything longer should become a reply-chain thread, not a clipped post.
- Do not design a handoff where one agent approves another's draft. Agent keys cannot call approve_post; that step belongs to a person or an owner key.
- Character limit: 300 graphemes per post. An emoji or an accented letter counts as 1 grapheme even if it uses several bytes.
- Media per post: Up to 4 images, or 1 video. Images and video cannot be mixed in one post.
- Image size: The AT Protocol image embed accepts blobs of about 1 MB each; the official app compresses larger photos. SocialHandoff checks for 1 MB per image.
- Video: Up to 3 minutes and 100 MB, MP4. SocialHandoff does not publish video to Bluesky.
Frequently asked questions
Does this work with non-OpenAI models in the SDK?
The MCP server does not care which model calls it. Any model the Agents SDK can drive can call draft_post.
How does a OpenAI Agents SDK pipeline attach images to a Bluesky post?
Upload each image to /v1/media with its alt text, then pass the returned ids as mediaIds. Keep each file under 1 MB and use at most 4.
Does it support custom domain handles on Bluesky?
Yes. Connect with whatever handle you sign in with, including a domain handle. Mentions of other handles become clickable facets on publish.