Skip to main content

Migration Guide

Current State​

You currently have search tools hardcoded in:

  • backend/src/tools/search.tools.ts
  • backend/src/services/searchProvider.service.ts
  • backend/src/tools/handlers/searchToolHandler.ts

Migration Steps​

Step 1: Create Search Extension​

# Copy template
cp -r packages/agentos-extensions/ext-template packages/agentos-extensions/ext-search

# Update package.json name to @framers/agentos-ext-search
# Update manifest.json id to com.framers.ext.search

Step 2: Port Search Tool​

Move logic from backend/src/tools/search.tools.ts to extension:

// packages/agentos-extensions/ext-search/src/tools/webSearch.ts
import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos';

export class WebSearchTool implements ITool {
  readonly id = 'com.framers.ext.search.webSearch';
  readonly name = 'webSearch';
  // ... port implementation
}

Step 3: Port Search Service​

Move searchProvider.service.ts logic into extension:

// packages/agentos-extensions/ext-search/src/services/searchProvider.ts
export class SearchProviderService {
  // ... port implementation
}

Step 4: Update AgentOS Configuration​

// backend/src/integrations/agentos/agentos.integration.ts
import { createExtensionPack as createSearchExtension } from '@framers/agentos-ext-search';

async function buildEmbeddedAgentOSConfig(): Promise<AgentOSConfig> {
  // ...
  return {
    // ... other config
    extensionManifest: {
      packs: [
        {
          factory: () => createSearchExtension({
            manifestEntry: {} as any,
            source: { sourceName: '@framers/agentos-ext-search' },
            options: {
              search: {
                provider: 'serper',
                apiKey: process.env.SERPER_API_KEY
              }
            }
          })
        }
      ]
    }
  };
}

Step 5: Remove Hardcoded Tools​

  1. Delete:

    • backend/src/tools/search.tools.ts
    • backend/src/services/searchProvider.service.ts
    • backend/src/tools/handlers/searchToolHandler.ts
    • backend/src/tools/handlers/index.ts (if only search)

  2. Remove from persona registry:

    • Remove import { SearchAgentTools } from agentos.persona-registry.ts
    • Remove search_tools from TOOLSETS
    • Remove toolsetIds: ['search_tools'] from personas

Step 6: Test Migration​

// Test that extension loads
const agentos = new AgentOS();
await agentos.initialize(config);
const tool = agentos.toolExecutor.getTool('webSearch');
expect(tool).toBeDefined();

Benefits After Migration​

  1. Modularity: Search tools in separate package
  2. Versioning: Independent version management
  3. Testing: Isolated test suite
  4. Distribution: Published to npm as @framers/agentos-ext-search
  5. Community: Others can use/improve the extension

Timeline​

  1. Phase 1: Create extension structure (done)
  2. Phase 2: Port search tools to extension
  3. Phase 3: Test with AgentOS runtime
  4. Phase 4: Publish to npm
  5. Phase 5: Remove hardcoded implementation

Rollback Plan​

If issues arise:

  1. Keep hardcoded tools as fallback
  2. Use feature flag to toggle between implementations
  3. Gradual migration persona by persona