LangChain to OSSA Migration Guide

Overview

What is LangChain?

LangChain is a Python framework for building applications powered by large language models (LLMs). It provides abstractions for:

• Agents: Autonomous decision-making systems that use LLMs
• Tools: External functions agents can call
• Chains: Sequential execution pipelines
• Memory: Conversation and state persistence
• Prompt Templates: Reusable prompt structures
• Vector Stores: Document retrieval and embedding management

Why Migrate to OSSA?

OSSA (Open Standard for Software Agents) provides several advantages over LangChain:

1. Language Agnostic: OSSA is a specification, not a framework. Works with TypeScript, Python, Go, Rust, etc.
2. OpenAPI-First: Built on web standards with REST APIs at the core
3. Production-Ready: Built-in monitoring, health checks, resource management, and compliance
4. Interoperability: Native bridges to MCP, OpenAPI, LangChain, CrewAI, AutoGen, and A2A protocols
5. Enterprise Features: Audit logging, policy enforcement, encryption, and compliance frameworks (ISO42001, SOC2, GDPR)
6. Cloud Native: Kubernetes-ready with proper resource limits and scaling
7. Type Safety: JSON Schema for all inputs/outputs with automatic validation

Migration Complexity: [object Object]

Estimated Time: 2-4 hours per agent depending on complexity

Difficulty Factors:

• ✅ Straightforward for simple agents with basic tools
• ⚠️ Moderate for agents with memory and chains
• ⚠️ Complex for multi-agent orchestration and custom callbacks

---

Conceptual Mapping

---

Migration Strategy

Phase 1: Assessment

1. Inventory your LangChain components

   • List all agents, tools, chains, and memory stores
   • Document LLM providers and models used
   • Identify custom callbacks and parsers

2. Map dependencies

   • External APIs and services
   • Vector databases and document stores
   • Authentication and secrets management

3. Define success criteria

   • Functional parity with existing LangChain implementation
   • Performance benchmarks
   • Monitoring and observability requirements

Phase 2: Design

1. Create OSSA agent structure

   buildkit agents create \
     --name your-agent \
     --type worker \
     --capabilities tool1,tool2,tool3 \
     --enable-mcp \
     --enable-openapi

2. Map each LangChain tool to OSSA capability

   • Define input schemas (replace prompt templates)
   • Define output schemas (replace output parsers)
   • Document capability purpose and examples

3. Design state management strategy

   • Choose state provider (Redis, PostgreSQL, in-memory)
   • Define state schema
   • Plan state persistence and retrieval

Phase 3: Implementation

1. Migrate tools to capabilities (see examples below)
2. Implement LLM integration (OpenAI, Anthropic, etc.)
3. Add state management (if using memory)
4. Configure monitoring and health checks
5. Set up authentication and security

Phase 4: Testing

1. Unit tests for each capability
2. Integration tests for workflows
3. Performance testing against benchmarks
4. Load testing for production readiness

Phase 5: Deployment

1. Deploy to staging environment
2. Run parallel with LangChain (if possible)
3. Monitor metrics and compare
4. Gradually shift traffic
5. Decommission LangChain implementation

---

Migration Examples

Example 1: Simple LangChain Agent with Tools

Original LangChain Code

from langchain.agents import initialize_agent, Tool, AgentType
from langchain.llms import OpenAI
from langchain.tools import BaseTool

# Define tools
class CalculatorTool(BaseTool):
    name = "Calculator"
    description = "Useful for math calculations. Input should be a math expression."

    def _run(self, query: str) -> str:
        try:
            return str(eval(query))
        except Exception as e:
            return f"Error: {str(e)}"

    def _arun(self, query: str):
        raise NotImplementedError("Async not supported")

class WeatherTool(BaseTool):
    name = "Weather"
    description = "Get current weather for a location. Input should be a city name."

    def _run(self, city: str) -> str:
        # Simplified for example
        return f"The weather in {city} is sunny, 72°F"

    def _arun(self, city: str):
        raise NotImplementedError("Async not supported")

# Create agent
tools = [CalculatorTool(), WeatherTool()]
llm = OpenAI(temperature=0, model="gpt-4")
agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# Run agent
result = agent.run("What's the weather in San Francisco? Also calculate 25 * 4.")
print(result)

OSSA Equivalent

Step 1: Create agent manifest - .agents/assistant-agent/agent.yml

ossaVersion: "0.3.3"
metadata:
  name: assistant-agent
  version: "1.0.0"
  description: "Assistant agent with calculator and weather capabilities"
  author: "Your Team"
  license: "MIT"
  tags:
    - assistant
    - calculator
    - weather
  created: "2025-11-10T00:00:00Z"
  updated: "2025-11-10T00:00:00Z"

agent:
  id: assistant-agent
  name: Assistant Agent
  version: 1.0.0
  role: workflow

  runtime:
    type: local
    command: ["node", "dist/index.js"]
    environment:
      NODE_ENV: production
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    resources:
      cpu: "500m"
      memory: "512Mi"

  llm:
    provider: openai
    model: gpt-4
    temperature: 0
    max_tokens: 2000

  capabilities:
    - name: calculate
      description: "Perform mathematical calculations. Input should be a math expression."
      input_schema:
        type: object
        required: ["expression"]
        properties:
          expression:
            type: string
            description: "Mathematical expression to evaluate"
            examples: ["2 + 2", "sqrt(16)", "25 * 4"]
      output_schema:
        type: object
        required: ["result"]
        properties:
          result:
            type: number
            description: "Calculated result"
          error:
            type: string
            description: "Error message if calculation failed"

    - name: get_weather
      description: "Get current weather for a location. Input should be a city name."
      input_schema:
        type: object
        required: ["city"]
        properties:
          city:
            type: string
            description: "City name to get weather for"
            examples: ["San Francisco", "New York", "London"]
          country:
            type: string
            description: "Optional country code (e.g., US, GB)"
      output_schema:
        type: object
        required: ["city", "temperature", "conditions"]
        properties:
          city:
            type: string
            description: "City name"
          temperature:
            type: string
            description: "Temperature with unit"
          conditions:
            type: string
            description: "Weather conditions"

  integration:
    protocol: http
    endpoints:
      base_url: "http://localhost:3000"
      health: "/health"
      metrics: "/metrics"
      openapi: "/openapi.json"

  monitoring:
    traces: true
    metrics: true
    logs: true
    health_check:
      enabled: true
      interval_seconds: 30
      timeout_seconds: 5

  policies:
    encryption: true
    audit: true
    rate_limiting:
      enabled: true
      requests_per_minute: 60

  bridge:
    mcp:
      enabled: true
      server_type: stdio
      tools:
        - name: calculate
          capability: calculate
        - name: get_weather
          capability: get_weather
    openapi:
      enabled: true
      spec_version: "3.1"

Step 2: Implement capabilities - .agents/assistant-agent/src/index.ts

import { FastifyInstance } from 'fastify';
import { OSSAAgent } from '@agent-buildkit/core';

interface CalculateInput {
  expression: string;
}

interface CalculateOutput {
  result?: number;
  error?: string;
}

interface WeatherInput {
  city: string;
  country?: string;
}

interface WeatherOutput {
  city: string;
  temperature: string;
  conditions: string;
}

class AssistantAgent extends OSSAAgent {
  async onCapability(
    name: string,
    input: Record<string, any>
  ): Promise<Record<string, any>> {
    switch (name) {
      case 'calculate':
        return this.calculate(input as CalculateInput);
      case 'get_weather':
        return this.getWeather(input as WeatherInput);
      default:
        throw new Error(`Unknown capability: ${name}`);
    }
  }

  private async calculate(input: CalculateInput): Promise<CalculateOutput> {
    try {
      // Safe evaluation using a math library instead of eval()
      const { evaluate } = await import('mathjs');
      const result = evaluate(input.expression);

      this.logger.info('Calculation performed', {
        expression: input.expression,
        result,
      });

      return { result: Number(result) };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      this.logger.error('Calculation failed', {
        expression: input.expression,
        error: errorMessage,
      });
      return { error: errorMessage };
    }
  }

  private async getWeather(input: WeatherInput): Promise<WeatherOutput> {
    // In production, call actual weather API
    // For example purposes, simplified response
    this.logger.info('Weather lookup', { city: input.city });

    // Example: Call OpenWeatherMap API
    // const response = await fetch(
    //   `https://api.openweathermap.org/data/2.5/weather?q=${input.city}&appid=${process.env.WEATHER_API_KEY}`
    // );
    // const data = await response.json();

    return {
      city: input.city,
      temperature: '72°F',
      conditions: 'sunny',
    };
  }
}

// Start the agent
const agent = new AssistantAgent({
  manifestPath: './agent.yml',
  port: 3000,
});

agent.start().catch((error) => {
  console.error('Failed to start agent:', error);
  process.exit(1);
});

Step 3: Package configuration - .agents/assistant-agent/package.json

{
  "name": "assistant-agent",
  "version": "0.3.3",
  "description": "OSSA assistant agent with calculator and weather capabilities",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "test": "jest"
  },
  "dependencies": {
    "@agent-buildkit/core": "^1.0.0",
    "fastify": "^4.25.0",
    "mathjs": "^12.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.3.0"
  }
}

Conversion Steps:

1. ✅ Mapped CalculatorTool → calculate capability with JSON schemas
2. ✅ Mapped WeatherTool → get_weather capability with JSON schemas
3. ✅ Configured OpenAI LLM in manifest (no code changes needed)
4. ✅ Added monitoring, health checks, and policies
5. ✅ Enabled MCP bridge for Claude Desktop integration
6. ✅ Used type-safe implementation with proper error handling

---

Example 2: LangChain Agent with Memory

Original LangChain Code

from langchain.agents import initialize_agent, Tool, AgentType
from langchain.llms import OpenAI
from langchain.memory import ConversationBufferMemory

# Define tools
tools = [
    Tool(
        name="Search",
        func=lambda query: f"Search results for: {query}",
        description="Useful for searching information"
    )
]

# Create memory
memory = ConversationBufferMemory(
    memory_key="chat_history",
    return_messages=True
)

# Create agent with memory
llm = OpenAI(temperature=0.7)
agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,
    memory=memory,
    verbose=True
)

# Conversations persist across runs
agent.run("Hi, my name is Alice")
agent.run("What's my name?")  # Should remember "Alice"

OSSA Equivalent

Agent manifest - .agents/conversational-agent/agent.yml

ossaVersion: "0.3.3"
metadata:
  name: conversational-agent
  version: "1.0.0"
  description: "Conversational agent with memory and search capability"

agent:
  id: conversational-agent
  name: Conversational Agent
  version: 1.0.0
  role: workflow

  runtime:
    type: local
    command: ["node", "dist/index.js"]
    environment:
      NODE_ENV: production
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      REDIS_URL: ${REDIS_URL}
    resources:
      cpu: "500m"
      memory: "512Mi"

  llm:
    provider: openai
    model: gpt-4
    temperature: 0.7
    max_tokens: 2000

  # State management configuration
  state:
    provider: redis
    config:
      url: ${REDIS_URL}
      ttl_seconds: 3600
      key_prefix: "agent:conversational:"

  capabilities:
    - name: search
      description: "Search for information on the web"
      input_schema:
        type: object
        required: ["query"]
        properties:
          query:
            type: string
            description: "Search query"
      output_schema:
        type: object
        required: ["results"]
        properties:
          results:
            type: string
            description: "Search results"

    - name: chat
      description: "Have a conversation with memory of previous interactions"
      input_schema:
        type: object
        required: ["message", "user_id"]
        properties:
          message:
            type: string
            description: "User message"
          user_id:
            type: string
            description: "Unique user identifier for memory isolation"
      output_schema:
        type: object
        required: ["response"]
        properties:
          response:
            type: string
            description: "Agent response"
          context:
            type: object
            description: "Conversation context"

  integration:
    protocol: http
    endpoints:
      base_url: "http://localhost:3000"

  monitoring:
    traces: true
    metrics: true
    logs: true

Implementation - .agents/conversational-agent/src/index.ts

import { FastifyInstance } from 'fastify';
import { OSSAAgent } from '@agent-buildkit/core';
import { Redis } from 'ioredis';
import { OpenAI } from 'openai';

interface ChatInput {
  message: string;
  user_id: string;
}

interface ChatOutput {
  response: string;
  context: {
    history_length: number;
    timestamp: string;
  };
}

interface SearchInput {
  query: string;
}

interface SearchOutput {
  results: string;
}

interface ConversationMessage {
  role: 'user' | 'assistant';
  content: string;
  timestamp: string;
}

class ConversationalAgent extends OSSAAgent {
  private redis: Redis;
  private openai: OpenAI;

  constructor(config: any) {
    super(config);

    // Initialize Redis for state management
    this.redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');

    // Initialize OpenAI client
    this.openai = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });
  }

  async onCapability(
    name: string,
    input: Record<string, any>
  ): Promise<Record<string, any>> {
    switch (name) {
      case 'search':
        return this.search(input as SearchInput);
      case 'chat':
        return this.chat(input as ChatInput);
      default:
        throw new Error(`Unknown capability: ${name}`);
    }
  }

  private async search(input: SearchInput): Promise<SearchOutput> {
    // In production, integrate with actual search API (Google, Bing, etc.)
    this.logger.info('Performing search', { query: input.query });

    return {
      results: `Search results for: ${input.query}`,
    };
  }

  private async chat(input: ChatInput): Promise<ChatOutput> {
    const { message, user_id } = input;

    // Get conversation history from Redis
    const history = await this.getConversationHistory(user_id);

    // Add user message to history
    const userMessage: ConversationMessage = {
      role: 'user',
      content: message,
      timestamp: new Date().toISOString(),
    };
    history.push(userMessage);

    // Prepare messages for OpenAI
    const messages = history.map((msg) => ({
      role: msg.role,
      content: msg.content,
    }));

    // Call OpenAI
    const completion = await this.openai.chat.completions.create({
      model: 'gpt-4',
      messages: messages as any,
      temperature: 0.7,
    });

    const assistantResponse = completion.choices[0].message.content || '';

    // Add assistant response to history
    const assistantMessage: ConversationMessage = {
      role: 'assistant',
      content: assistantResponse,
      timestamp: new Date().toISOString(),
    };
    history.push(assistantMessage);

    // Save updated history to Redis
    await this.saveConversationHistory(user_id, history);

    this.logger.info('Chat response generated', {
      user_id,
      history_length: history.length,
    });

    return {
      response: assistantResponse,
      context: {
        history_length: history.length,
        timestamp: new Date().toISOString(),
      },
    };
  }

  private async getConversationHistory(
    userId: string
  ): Promise<ConversationMessage[]> {
    const key = `agent:conversational:${userId}:history`;
    const data = await this.redis.get(key);

    if (!data) {
      return [];
    }

    try {
      return JSON.parse(data);
    } catch (error) {
      this.logger.error('Failed to parse conversation history', { error });
      return [];
    }
  }

  private async saveConversationHistory(
    userId: string,
    history: ConversationMessage[]
  ): Promise<void> {
    const key = `agent:conversational:${userId}:history`;

    // Keep only last 20 messages to prevent unlimited growth
    const trimmedHistory = history.slice(-20);

    await this.redis.setex(
      key,
      3600, // 1 hour TTL
      JSON.stringify(trimmedHistory)
    );
  }

  async onShutdown(): Promise<void> {
    await this.redis.quit();
  }
}

// Start the agent
const agent = new ConversationalAgent({
  manifestPath: './agent.yml',
  port: 3000,
});

agent.start().catch((error) => {
  console.error('Failed to start agent:', error);
  process.exit(1);
});

Conversion Steps:

1. ✅ Replaced ConversationBufferMemory with Redis state management
2. ✅ Added state configuration in manifest
3. ✅ Implemented conversation history persistence with TTL
4. ✅ Added user isolation (separate history per user_id)
5. ✅ Implemented history trimming to prevent unlimited growth
6. ✅ Added proper cleanup on shutdown

---

Example 3: LangChain Sequential Chain

Original LangChain Code

from langchain import PromptTemplate, LLMChain
from langchain.chains import SequentialChain
from langchain.llms import OpenAI

llm = OpenAI(temperature=0.7)

# First chain: Generate synopsis
synopsis_template = """You are a creative writer. Write a one-sentence synopsis for a story about {topic}."""
synopsis_prompt = PromptTemplate(input_variables=["topic"], template=synopsis_template)
synopsis_chain = LLMChain(llm=llm, prompt=synopsis_prompt, output_key="synopsis")

# Second chain: Expand synopsis into story
story_template = """Based on this synopsis: {synopsis}

Write a short story (3 paragraphs) that brings this synopsis to life."""
story_prompt = PromptTemplate(input_variables=["synopsis"], template=story_template)
story_chain = LLMChain(llm=llm, prompt=story_prompt, output_key="story")

# Third chain: Generate title
title_template = """Given this story: {story}

Generate a catchy title (5 words or less)."""
title_prompt = PromptTemplate(input_variables=["story"], template=title_template)
title_chain = LLMChain(llm=llm, prompt=title_prompt, output_key="title")

# Sequential chain
overall_chain = SequentialChain(
    chains=[synopsis_chain, story_chain, title_chain],
    input_variables=["topic"],
    output_variables=["synopsis", "story", "title"],
    verbose=True
)

# Run
result = overall_chain({"topic": "artificial intelligence"})
print(f"Title: {result['title']}")
print(f"Synopsis: {result['synopsis']}")
print(f"Story: {result['story']}")

OSSA Equivalent

Agent manifest - .agents/story-writer-agent/agent.yml

ossaVersion: "0.3.3"
metadata:
  name: story-writer-agent
  version: "1.0.0"
  description: "Sequential story generation agent with synopsis, story, and title generation"

agent:
  id: story-writer-agent
  name: Story Writer Agent
  version: 1.0.0
  role: workflow

  runtime:
    type: local
    command: ["node", "dist/index.js"]
    environment:
      NODE_ENV: production
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    resources:
      cpu: "1000m"
      memory: "1Gi"

  llm:
    provider: openai
    model: gpt-4
    temperature: 0.7
    max_tokens: 4000

  capabilities:
    - name: generate_synopsis
      description: "Generate a one-sentence story synopsis"
      input_schema:
        type: object
        required: ["topic"]
        properties:
          topic:
            type: string
            description: "Story topic"
      output_schema:
        type: object
        required: ["synopsis"]
        properties:
          synopsis:
            type: string
            description: "One-sentence story synopsis"

    - name: expand_story
      description: "Expand synopsis into full story"
      input_schema:
        type: object
        required: ["synopsis"]
        properties:
          synopsis:
            type: string
            description: "Story synopsis to expand"
      output_schema:
        type: object
        required: ["story"]
        properties:
          story:
            type: string
            description: "Full story (3 paragraphs)"

    - name: generate_title
      description: "Generate catchy title from story"
      input_schema:
        type: object
        required: ["story"]
        properties:
          story:
            type: string
            description: "Full story text"
      output_schema:
        type: object
        required: ["title"]
        properties:
          title:
            type: string
            description: "Catchy title (5 words or less)"

    - name: write_complete_story
      description: "Write complete story with synopsis, body, and title (sequential workflow)"
      workflow:
        type: sequential
        steps:
          - capability: generate_synopsis
            input_mapping:
              topic: "$.input.topic"
            output_key: "synopsis_result"

          - capability: expand_story
            input_mapping:
              synopsis: "$.synopsis_result.synopsis"
            output_key: "story_result"

          - capability: generate_title
            input_mapping:
              story: "$.story_result.story"
            output_key: "title_result"

      input_schema:
        type: object
        required: ["topic"]
        properties:
          topic:
            type: string
            description: "Story topic"

      output_schema:
        type: object
        required: ["title", "synopsis", "story"]
        properties:
          title:
            type: string
            description: "Story title"
          synopsis:
            type: string
            description: "Story synopsis"
          story:
            type: string
            description: "Full story"

  integration:
    protocol: http
    endpoints:
      base_url: "http://localhost:3000"

  monitoring:
    traces: true
    metrics: true
    logs: true

Implementation - .agents/story-writer-agent/src/index.ts

import { OSSAAgent } from '@agent-buildkit/core';
import { OpenAI } from 'openai';

interface SynopsisInput {
  topic: string;
}

interface SynopsisOutput {
  synopsis: string;
}

interface StoryInput {
  synopsis: string;
}

interface StoryOutput {
  story: string;
}

interface TitleInput {
  story: string;
}

interface TitleOutput {
  title: string;
}

interface CompleteStoryInput {
  topic: string;
}

interface CompleteStoryOutput {
  title: string;
  synopsis: string;
  story: string;
}

class StoryWriterAgent extends OSSAAgent {
  private openai: OpenAI;

  constructor(config: any) {
    super(config);
    this.openai = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });
  }

  async onCapability(
    name: string,
    input: Record<string, any>
  ): Promise<Record<string, any>> {
    switch (name) {
      case 'generate_synopsis':
        return this.generateSynopsis(input as SynopsisInput);
      case 'expand_story':
        return this.expandStory(input as StoryInput);
      case 'generate_title':
        return this.generateTitle(input as TitleInput);
      case 'write_complete_story':
        return this.writeCompleteStory(input as CompleteStoryInput);
      default:
        throw new Error(`Unknown capability: ${name}`);
    }
  }

  private async generateSynopsis(input: SynopsisInput): Promise<SynopsisOutput> {
    const completion = await this.openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        {
          role: 'system',
          content: 'You are a creative writer.',
        },
        {
          role: 'user',
          content: `Write a one-sentence synopsis for a story about ${input.topic}.`,
        },
      ],
      temperature: 0.7,
    });

    const synopsis = completion.choices[0].message.content || '';

    this.logger.info('Synopsis generated', { topic: input.topic });

    return { synopsis };
  }

  private async expandStory(input: StoryInput): Promise<StoryOutput> {
    const completion = await this.openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        {
          role: 'system',
          content: 'You are a creative writer who expands story synopses into full narratives.',
        },
        {
          role: 'user',
          content: `Based on this synopsis: ${input.synopsis}\n\nWrite a short story (3 paragraphs) that brings this synopsis to life.`,
        },
      ],
      temperature: 0.7,
      max_tokens: 2000,
    });

    const story = completion.choices[0].message.content || '';

    this.logger.info('Story expanded', { synopsis_length: input.synopsis.length });

    return { story };
  }

  private async generateTitle(input: TitleInput): Promise<TitleOutput> {
    const completion = await this.openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        {
          role: 'system',
          content: 'You are a creative writer who creates catchy titles.',
        },
        {
          role: 'user',
          content: `Given this story: ${input.story}\n\nGenerate a catchy title (5 words or less).`,
        },
      ],
      temperature: 0.7,
    });

    const title = completion.choices[0].message.content || '';

    this.logger.info('Title generated');

    return { title };
  }

  private async writeCompleteStory(
    input: CompleteStoryInput
  ): Promise<CompleteStoryOutput> {
    // Execute sequential workflow
    this.logger.info('Starting complete story workflow', { topic: input.topic });

    // Step 1: Generate synopsis
    const synopsisResult = await this.generateSynopsis({ topic: input.topic });

    // Step 2: Expand to full story
    const storyResult = await this.expandStory({ synopsis: synopsisResult.synopsis });

    // Step 3: Generate title
    const titleResult = await this.generateTitle({ story: storyResult.story });

    this.logger.info('Complete story workflow finished', {
      topic: input.topic,
      title: titleResult.title,
    });

    return {
      title: titleResult.title,
      synopsis: synopsisResult.synopsis,
      story: storyResult.story,
    };
  }
}

// Start the agent
const agent = new StoryWriterAgent({
  manifestPath: './agent.yml',
  port: 3000,
});

agent.start().catch((error) => {
  console.error('Failed to start agent:', error);
  process.exit(1);
});

Conversion Steps:

1. ✅ Mapped each LLMChain to an OSSA capability
2. ✅ Defined workflow with sequential execution type
3. ✅ Used input_mapping to pass outputs between steps
4. ✅ Implemented sequential execution in code
5. ✅ Added comprehensive logging for each step
6. ✅ Made each step independently testable

---

Advanced Migration Topics

Migrating Custom Callbacks

LangChain:

from langchain.callbacks.base import BaseCallbackHandler

class MyCallback(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kwargs):
        print(f"LLM started with prompts: {prompts}")

    def on_llm_end(self, response, **kwargs):
        print(f"LLM finished: {response}")

OSSA: Use built-in monitoring with OpenTelemetry traces:

class MyAgent extends OSSAAgent {
  async onCapability(name: string, input: any): Promise<any> {
    // Automatic tracing with spans
    const span = this.tracer.startSpan(`capability.${name}`);

    try {
      span.setAttribute('input.size', JSON.stringify(input).length);

      const result = await this.processCapability(name, input);

      span.setAttribute('output.size', JSON.stringify(result).length);
      span.setStatus({ code: SpanStatusCode.OK });

      return result;
    } catch (error) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      throw error;
    } finally {
      span.end();
    }
  }
}

Migrating Vector Stores

LangChain:

from langchain.vectorstores import Pinecone
from langchain.embeddings import OpenAIEmbeddings

embeddings = OpenAIEmbeddings()
vectorstore = Pinecone.from_documents(docs, embeddings)
results = vectorstore.similarity_search(query, k=5)

OSSA: Create a separate capability for vector search:

capabilities:
  - name: vector_search
    description: "Search documents using semantic similarity"
    input_schema:
      type: object
      required: ["query"]
      properties:
        query:
          type: string
        top_k:
          type: integer
          default: 5
    output_schema:
      type: object
      required: ["results"]
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              document:
                type: string
              score:
                type: number

private async vectorSearch(input: VectorSearchInput): Promise<VectorSearchOutput> {
  // Use Pinecone SDK directly
  const pinecone = new Pinecone({ apiKey: process.env.PINECONE_API_KEY });
  const index = pinecone.index('your-index');

  // Generate embedding
  const embedding = await this.openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: input.query,
  });

  // Query Pinecone
  const queryResponse = await index.query({
    vector: embedding.data[0].embedding,
    topK: input.top_k || 5,
    includeMetadata: true,
  });

  return {
    results: queryResponse.matches.map((match) => ({
      document: match.metadata?.text as string,
      score: match.score || 0,
    })),
  };
}

Migrating Multi-Agent Systems

LangChain:

from langchain.agents import initialize_agent
from langchain.agents import AgentType

# Create multiple agents
researcher = initialize_agent(research_tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
writer = initialize_agent(writing_tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
editor = initialize_agent(editing_tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)

# Coordinate manually
research = researcher.run("Research AI trends")
draft = writer.run(f"Write article based on: {research}")
final = editor.run(f"Edit this draft: {draft}")

OSSA: Use orchestrator agent with A2A (Agent-to-Agent) communication:

ossaVersion: "0.3.3"
agent:
  id: article-orchestrator
  name: Article Orchestrator
  role: orchestration

  capabilities:
    - name: produce_article
      description: "Coordinate research, writing, and editing agents to produce an article"
      workflow:
        type: sequential
        agents:
          - agent_id: researcher-agent
            capability: research
            input_mapping:
              topic: "$.input.topic"
            output_key: "research_results"

          - agent_id: writer-agent
            capability: write_article
            input_mapping:
              research: "$.research_results.findings"
            output_key: "draft_article"

          - agent_id: editor-agent
            capability: edit
            input_mapping:
              draft: "$.draft_article.text"
            output_key: "final_article"

  bridge:
    a2a:
      enabled: true
      protocol: grpc
      discovery:
        type: service_mesh
        namespace: agents

---

Validation

Test Your Migration

# Navigate to agent directory
cd .agents/your-agent

# Install dependencies
npm install

# Build
npm run build

# Validate manifest
buildkit agents validate ./agent.yml

# Run agent locally
npm start

# Test capability
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "your_capability",
    "input": {
      "test": "data"
    }
  }'

# Check health
curl http://localhost:3000/health

# View metrics
curl http://localhost:3000/metrics

# View OpenAPI spec
curl http://localhost:3000/openapi.json

Integration Tests

Create integration tests to verify parity:

import { describe, it, expect } from '@jest/globals';
import { OSSAAgentClient } from '@agent-buildkit/client';

describe('Agent Migration Tests', () => {
  const client = new OSSAAgentClient({
    baseUrl: 'http://localhost:3000',
  });

  it('should produce same results as LangChain version', async () => {
    const input = { topic: 'artificial intelligence' };

    const result = await client.execute('your_capability', input);

    expect(result).toHaveProperty('expected_output');
    // Compare with LangChain baseline results
  });

  it('should handle errors gracefully', async () => {
    const invalidInput = { invalid: 'data' };

    await expect(
      client.execute('your_capability', invalidInput)
    ).rejects.toThrow();
  });
});

---

FAQ

Q: Can I use existing LangChain tools directly in OSSA?

A: Yes, with the LangChain bridge. Add to your manifest:

bridge:
  langchain:
    enabled: true
    tool_class: YourLangChainTool
    chain_type: agent

Then wrap your LangChain tools:

import { LangChainBridge } from '@agent-buildkit/bridges';
import { YourLangChainTool } from './langchain-tools';

const bridge = new LangChainBridge({
  tools: [new YourLangChainTool()],
});

// Use in your agent
private async yourCapability(input: any): Promise<any> {
  return bridge.executeTool('YourLangChainTool', input);
}

Q: How do I handle async operations in OSSA?

A: All OSSA capabilities are async by default. Use standard async/await:

async onCapability(name: string, input: any): Promise<any> {
  // All operations are naturally async
  const result1 = await this.externalApiCall();
  const result2 = await this.databaseQuery();

  return { result1, result2 };
}

For parallel execution:

const [result1, result2, result3] = await Promise.all([
  this.operation1(),
  this.operation2(),
  this.operation3(),
]);

Q: What about LangChain agents with multiple LLMs?

A: Configure multiple LLM providers in your agent:

agent:
  llm:
    primary:
      provider: openai
      model: gpt-4
    secondary:
      provider: anthropic
      model: claude-3-opus
    fallback:
      provider: openai
      model: gpt-3.5-turbo

Then use in code:

private async generateResponse(input: any): Promise<any> {
  try {
    // Try primary LLM
    return await this.callLLM('primary', input);
  } catch (error) {
    this.logger.warn('Primary LLM failed, trying secondary');
    try {
      return await this.callLLM('secondary', input);
    } catch (error) {
      this.logger.warn('Secondary LLM failed, using fallback');
      return await this.callLLM('fallback', input);
    }
  }
}

Q: How do I migrate LangChain's output parsers?

A: Use JSON Schema in output_schema for automatic validation:

capabilities:
  - name: extract_data
    output_schema:
      type: object
      required: ["name", "email", "phone"]
      properties:
        name:
          type: string
          pattern: "^[A-Za-z ]+$"
        email:
          type: string
          format: email
        phone:
          type: string
          pattern: "^\\+?[1-9]\\d{1,14}$"

OSSA automatically validates output against the schema and returns errors if validation fails.

Q: What about LangChain's document loaders?

A: Create dedicated capabilities for document processing:

capabilities:
  - name: load_documents
    description: "Load and process documents from various sources"
    input_schema:
      type: object
      required: ["source_type", "source_path"]
      properties:
        source_type:
          type: string
          enum: ["pdf", "docx", "txt", "url", "s3"]
        source_path:
          type: string
    output_schema:
      type: object
      required: ["documents"]
      properties:
        documents:
          type: array
          items:
            type: object
            properties:
              content:
                type: string
              metadata:
                type: object

Q: How do I monitor agent performance compared to LangChain?

A: OSSA has built-in monitoring with OpenTelemetry:

1. Traces: Every capability execution is automatically traced
2. Metrics: Built-in metrics (execution time, success rate, etc.)
3. Logs: Structured logging with correlation IDs
4. Dashboards: Grafana/Prometheus integration

View metrics:

curl http://localhost:3000/metrics

# Example output:
# agent_executions_total{capability="chat",status="success"} 1523
# agent_execution_duration_ms{capability="chat",quantile="0.95"} 245
# agent_llm_tokens_used{model="gpt-4"} 45234

Q: Can I gradually migrate from LangChain?

A: Yes! Run both in parallel:

1. Deploy OSSA agent alongside LangChain
2. Route percentage of traffic to OSSA (e.g., 10%)
3. Compare results and metrics
4. Gradually increase OSSA traffic as confidence grows
5. Deprecate LangChain once OSSA is proven

Use feature flags or load balancer to control traffic split.

---

Performance Comparison

Benchmarks based on simple agent with 3 tools, tested on m5.large EC2 instance

---

Next Steps

After Migration

1. Set up CI/CD

   # .gitlab-ci.yml
   test:
     script:
       - cd .agents/your-agent
       - npm test
       - buildkit agents validate ./agent.yml
   
   deploy:
     script:
       - buildkit agents deploy --name your-agent --env production

2. Configure monitoring

   # Enable Prometheus metrics
   buildkit monitoring setup --agent your-agent
   
   # Set up alerts
   buildkit monitoring alerts create \
     --agent your-agent \
     --metric execution_duration_ms \
     --threshold 1000 \
     --severity critical

3. Enable MCP for Claude Desktop

   # Generate Claude Desktop config
   buildkit mcpb claude-config --agent your-agent
   
   # Add to ~/.config/claude/claude_desktop_config.json

4. Create documentation

   # Auto-generate API docs
   buildkit docs generate --agent your-agent
   
   # Publish to GitLab wiki
   buildkit docs publish --agent your-agent

5. Join the community

   • OSSA Specification
   • Agent BuildKit
   • Examples Repository
   • Issue Tracker

---

Additional Resources

Documentation

• OSSA Complete Agent Reference
• OSSA Quick Reference
• Agent BuildKit CLI Reference
• MCP Integration Guide
• Getting Started Guide

Examples

• Simple Worker Agent
• Orchestrator Agent
• Multi-Agent System

Tools

• Agent Validator
• Migration Script
• Agent Templates

Support

• Issues: https://gitlab.com/blueflyio/agent-platform/agent-buildkit/-/issues
• Discussions: https://gitlab.com/blueflyio/agent-platform/agent-buildkit/-/merge_requests
• Wiki: https://gitlab.com/blueflyio/agent-platform/agent-buildkit/-/wikis/home

---

Troubleshooting

Common Migration Issues

Issue: "Cannot find module '@agent-buildkit/core'"

Solution: Install the OSSA SDK:

npm install @agent-buildkit/core @agent-buildkit/client

Issue: "Invalid manifest: missing required field 'capabilities'"

Solution: Every OSSA agent must have at least one capability. Add:

capabilities:
  - name: your_capability
    input_schema: { type: object }
    output_schema: { type: object }

Issue: "LLM API key not found"

Solution: Set environment variable in manifest:

runtime:
  environment:
    OPENAI_API_KEY: ${OPENAI_API_KEY}

Or use secrets management:

buildkit secrets create --name openai-api-key --value sk-...

Issue: "Port 3000 already in use"

Solution: Change port in manifest or runtime:

integration:
  endpoints:
    base_url: "http://localhost:3001"

Or set via environment:

PORT=3001 npm start

Issue: "Memory limit exceeded"

Solution: Increase resource allocation:

runtime:
  resources:
    memory: "1Gi"  # Increase from default 512Mi

---

Version: 1.0.0 Last Updated: 2025-11-10 Migration Complexity: Medium Estimated Time: 2-4 hours per agent

---

For questions or issues with this migration guide, please create an issue at: https://gitlab.com/blueflyio/agent-platform/agent-buildkit/-/issues