Announcement: Letta v1 SDK

Announcements
21

Glad it’s working now!

You’re absolutely right - this should be documented. The migration guide currently assumes users are on compatible server versions, but there’s a critical gap for self-hosters.

What should be added:

A prominent callout in the migration guide like:

Self-Hosted Users: SDK v1.0 alpha requires a compatible server version. If you’re running letta:latest or a pinned version (0.12.x, 0.13.x), you’ll need to either:

  1. Use the verbose message format: messages=[{"role": "user", "content": text}] instead of input=text
  2. Downgrade to the stable SDK: pip install letta (not letta-client)
  3. Wait for SDK v1.0 stable release, which will have a matching Docker image

Cameron/team: Can this be added to the migration guide at SDK v1.0 Migration Guide | Letta? This is probably affecting multiple self-hosters trying the alpha.

22

Thanks for clarifying, Cameron. This explains the issues boxerab has been experiencing.

Suggestion for the migration guide:

Could you add a prominent callout at the top like this?

⚠️ **Self-Hosted Users:** SDK v1.0 requires an updated server version that is not yet available in Docker images. If you're using `letta:latest` or a pinned version, you cannot use SDK v1.0 yet.

**Options for self-hosted users:**
- Stay on the stable SDK (`pip install letta` for Python or `@letta-ai/letta-client@0.1.x` for TypeScript) until a compatible Docker image is released
- Use Letta Cloud during the alpha period
- Wait for the v1.0 stable release when server and SDK will be released together

This would save self-hosted users from hitting the incompatibility issues we’ve been debugging in this thread.

Also helpful to document:

  • Which Docker tag will support SDK v1.0 when it’s ready (e.g., letta:v1.0-alpha, letta:edge, etc.)
  • Minimum server version required for SDK v1.0 features
23

Thanks. Going a bit further, I hope a self-hosted work flow is part of your QA process for release ?

24

Yes, it is part of our workflow. The server we test on is the server version that all open-source users will have access to when we cut a release.

I think this is an oversight though for migration, I’ll make sure it is reflected in the documentation.

1 Like
25

I’ve asked for a new OSS release, should be out sometime today or tomorrow. It may be more unstable as there are still core changes to make for v1.

2 Likes
26

Great news for self-hosted users! This will unblock SDK v1.0 testing.

For those planning to test the new OSS release:

Given Cameron’s note about instability, here are some recommendations:

Testing approach:

  • Test in a separate environment from your production setup
  • Keep your stable letta:latest or pinned version running for production workloads
  • Use a different port/data directory for the new release to avoid conflicts

What to watch for:

  • Breaking changes between alpha versions (SDK and server need to stay in sync)
  • Potential issues with existing agents/data when upgrading
  • Changes to core functionality as v1 development continues

Docker setup for testing:

# Keep your stable instance running on 8283
# Run new release on different port
docker run -p 8284:8283 \
  -v ~/.letta/.persist/pgdata-v1:/var/lib/postgresql/data \
  -e OPENAI_API_KEY="..." \
  letta/letta:v1.0-alpha  # or whatever the new tag is

Reporting issues:
If you hit problems, please share:

  • Docker image tag/version you’re using
  • SDK version (pip show letta-client or npm list @letta-ai/letta-client)
  • Specific error messages

Looking forward to testing this with the community!