Migration Guide

This guide covers migrating existing lobster-custom-* packages to work with Lobster AI v1.0.0 and the new modular architecture.

What Changed in v1.0.0

Package Structure

Before (v0.x): Single monolithic package

• All agents bundled in lobster-ai
• Custom packages extended the monolith

After (v1.0.0): Modular package ecosystem

• lobster-ai is the lean core SDK
• Agents are separate packages (lobster-transcriptomics, etc.)
• pip install lobster-ai[full] installs all free agents

Breaking Changes

1. Entry point discovery is now primary

   • AGENT_REGISTRY dict removed
   • All agents discovered via lobster.agents entry point group
   • Your AGENT_CONFIG must be discoverable via entry points

2. Version constraint requirement

   • Agent packages must depend on lobster-ai~=1.0.0
   • This ensures compatibility across the ecosystem

3. Tier gating at runtime

   • Premium features gated via tier_requirement in AGENT_CONFIG
   • No changes needed for custom packages (enterprise tier)

What Stays the Same (Backward Compatibility)

Your lobster-custom-* package will continue working if:

1. Entry points registered in pyproject.toml:

   [project.entry-points."lobster.agents"]
   my_custom_agent = "lobster_custom_company.agents.my_agent:AGENT_CONFIG"

2. AGENT_CONFIG defined at module top:

   AGENT_CONFIG = AgentRegistryConfig(
       name="my_custom_agent",
       display_name="My Custom Agent",
       ...
   )

3. Factory signature follows contract:

   def create_my_agent(
       data_manager,
       callback_handler,
       agent_name,
       delegation_tools=None,
       workspace_path=None,
       **kwargs
   ) -> CompiledGraph:

Migration Checklist

Required Changes

• Update dependency: lobster-ai>=0.4.0 to lobster-ai~=1.0.0
• Verify entry points registered in pyproject.toml
• Verify AGENT_CONFIG at top of agent module (before heavy imports)

Recommended Changes

• Add tier_requirement='enterprise' to AGENT_CONFIG (optional but explicit)
• Add package_name='lobster-custom-yourcompany' to AGENT_CONFIG
• Test with lobster agents list to verify discovery

No Changes Needed

• Factory function implementation
• Service patterns (3-tuple return)
• Import paths within your package
• S3 delivery mechanism (enterprise packages only)

Testing Your Package

After updating, verify your package works:

# Install your package
pip install /path/to/lobster-custom-yourcompany

# Verify discovery
lobster agents list
# Should show your custom agent

# Verify info
lobster agents info my_custom_agent
# Should display agent details

# Test in session
lobster chat
# Your agent should be available for handoffs

Common Issues

Agent Not Discovered

Symptom: lobster agents list does not show your agent

Solutions:

1. Verify entry point in pyproject.toml matches import path
2. Run pip install -e . to refresh entry points
3. Check for import errors: python -c "from your_module import AGENT_CONFIG"

Version Conflict

Symptom: pip install fails with dependency conflict

Solutions:

1. Update to lobster-ai~=1.0.0 (compatible release)
2. Do not pin exact versions of lobster-ai dependencies

Import Errors After Upgrade

Symptom: ImportError: cannot import name 'X' from 'lobster'

Solutions:

1. Check if X was moved to a separate package
2. Core SDK imports unchanged (lobster.core.*, lobster.services.*)
3. Agent imports now from separate packages

Getting Help

• Documentation: https://docs.omics-os.com
• Plugin Contract: Plugin Contract
• Support: support@omics-os.com (Enterprise)