@bluefly/openstandardagents 0.3.1 → 0.3.3

package/spec/v0.3.3/extensions/langchain.md

@@ -0,0 +1,1092 @@
+# LangChain/LangGraph Extension for OSSA v0.3.3
+
+**Version:** 0.3.3
+**Status:** Stable
+**Last Updated:** 2025-12-31
+
+## Overview
+
+The `extensions.langchain` schema provides comprehensive bidirectional mapping between LangChain/LangGraph constructs and OSSA manifest primitives. This extension enables:
+
+- LCEL (LangChain Expression Language) chains to be represented as OSSA Workflows
+- LangGraph state machines mapped to OSSA Workflow kind with conditional branching
+- Tool/Function binding via OSSA capabilities abstraction
+- Memory systems (ConversationBufferMemory, VectorStoreMemory) mapped to OSSA state
+- Agent architectures (ReAct, OpenAI Functions, XML) to OSSA Agent kind
+- Callbacks integration with OSSA observability
+- Runnables as OSSA Task kind
+
+## Schema Definition
+
+```yaml
+extensions:
+  langchain:
+    type: object
+    description: "LangChain/LangGraph integration extension for OSSA v0.3.3"
+    properties:
+      enabled:
+        type: boolean
+        default: true
+        description: "Enable LangChain extension"
+
+      version:
+        type: string
+        pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+        description: "LangChain version compatibility (e.g., 0.3.0)"
+        examples:
+          - "0.3.0"
+          - "0.2.16"
+
+      chains:
+        type: array
+        description: "LCEL chain definitions mapped to OSSA constructs"
+        items:
+          $ref: "#/definitions/LangChainChainConfig"
+
+      graphs:
+        type: array
+        description: "LangGraph state machine definitions"
+        items:
+          $ref: "#/definitions/LangGraphConfig"
+
+      memory_type:
+        type: string
+        enum:
+          - conversation_buffer
+          - conversation_buffer_window
+          - conversation_summary
+          - vector_store
+          - entity
+          - combined
+          - none
+        default: none
+        description: "Memory backend type for stateful interactions"
+
+      memory_config:
+        type: object
+        description: "Memory-specific configuration"
+        properties:
+          max_token_limit:
+            type: integer
+            minimum: 100
+            maximum: 128000
+            description: "Maximum tokens for memory buffer"
+          k:
+            type: integer
+            minimum: 1
+            description: "Window size for conversation_buffer_window"
+          vector_store:
+            type: object
+            properties:
+              type:
+                type: string
+                enum: [chroma, qdrant, pinecone, weaviate, milvus, pgvector, faiss]
+              collection_name:
+                type: string
+              embedding_model:
+                type: string
+                description: "Embedding model for vectorization"
+              connection_string:
+                type: string
+                description: "Connection string reference (use env var)"
+
+      callbacks:
+        type: array
+        description: "LangChain callback handlers mapped to OSSA observability"
+        items:
+          $ref: "#/definitions/LangChainCallbackConfig"
+
+      runnable_config:
+        type: object
+        description: "Global RunnableConfig settings"
+        properties:
+          max_concurrency:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 5
+            description: "Maximum concurrent runnable executions"
+          recursion_limit:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+            description: "Maximum recursion depth for nested runnables"
+          tags:
+            type: array
+            items:
+              type: string
+            description: "Tags for filtering callbacks"
+          metadata:
+            type: object
+            additionalProperties: true
+            description: "Arbitrary metadata passed to callbacks"
+          configurable:
+            type: object
+            additionalProperties: true
+            description: "Configurable fields for runtime configuration"
+
+      agent_type:
+        type: string
+        enum:
+          - react
+          - openai_functions
+          - openai_tools
+          - xml
+          - structured_chat
+          - tool_calling
+          - langgraph_react
+          - custom
+        description: "LangChain agent architecture type"
+
+      agent_config:
+        type: object
+        description: "Agent-type-specific configuration"
+        properties:
+          handle_parsing_errors:
+            type: boolean
+            default: true
+          max_iterations:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 15
+          early_stopping_method:
+            type: string
+            enum: [force, generate]
+            default: generate
+          return_intermediate_steps:
+            type: boolean
+            default: false
+          trim_intermediate_steps:
+            type: integer
+            description: "Keep only last N intermediate steps"
+
+definitions:
+  LangChainChainConfig:
+    type: object
+    required:
+      - name
+      - type
+    properties:
+      name:
+        type: string
+        pattern: "^[a-z][a-z0-9_-]*$"
+        description: "Chain identifier"
+      type:
+        type: string
+        enum:
+          - llm
+          - prompt_template
+          - retrieval
+          - stuff_documents
+          - map_reduce
+          - refine
+          - map_rerank
+          - conversational_retrieval
+          - sql_database
+          - api
+          - transformation
+          - sequential
+          - router
+          - custom
+        description: "Chain type"
+      lcel_expression:
+        type: string
+        description: "LCEL expression string (e.g., 'prompt | llm | parser')"
+      components:
+        type: array
+        description: "Chain components for sequential chains"
+        items:
+          type: object
+          properties:
+            type:
+              type: string
+              enum: [prompt, llm, parser, retriever, tool, function, passthrough, itemgetter]
+            ref:
+              type: string
+              description: "Reference to component definition"
+            config:
+              type: object
+              additionalProperties: true
+      input_schema:
+        $ref: "#/definitions/JSONSchemaDefinition"
+      output_schema:
+        $ref: "#/definitions/JSONSchemaDefinition"
+      fallback:
+        type: object
+        description: "Fallback chain configuration"
+        properties:
+          chain_ref:
+            type: string
+          exceptions:
+            type: array
+            items:
+              type: string
+      batch_config:
+        type: object
+        properties:
+          max_concurrency:
+            type: integer
+          return_exceptions:
+            type: boolean
+            default: false
+
+  LangGraphConfig:
+    type: object
+    required:
+      - name
+      - nodes
+    properties:
+      name:
+        type: string
+        pattern: "^[a-z][a-z0-9_-]*$"
+        description: "Graph identifier"
+      state_schema:
+        $ref: "#/definitions/JSONSchemaDefinition"
+        description: "TypedDict/Pydantic state schema"
+      nodes:
+        type: array
+        description: "Graph nodes"
+        items:
+          type: object
+          required:
+            - id
+            - type
+          properties:
+            id:
+              type: string
+              description: "Node identifier"
+            type:
+              type: string
+              enum:
+                - agent
+                - tool
+                - function
+                - subgraph
+                - passthrough
+                - conditional
+                - human_in_loop
+            handler:
+              type: string
+              description: "Handler function/class reference"
+            ossa_ref:
+              type: string
+              description: "Reference to OSSA Task or Agent manifest"
+      edges:
+        type: array
+        description: "Graph edges (transitions)"
+        items:
+          type: object
+          required:
+            - from
+            - to
+          properties:
+            from:
+              type: string
+              description: "Source node ID or START"
+            to:
+              type: string
+              description: "Target node ID or END"
+            condition:
+              type: string
+              description: "Condition function reference for conditional edges"
+            condition_map:
+              type: object
+              description: "Map of condition values to target nodes"
+              additionalProperties:
+                type: string
+      entrypoint:
+        type: string
+        default: "START"
+        description: "Entry point node ID"
+      checkpointer:
+        type: object
+        description: "State persistence configuration"
+        properties:
+          type:
+            type: string
+            enum: [memory, sqlite, postgres, redis]
+          connection_string:
+            type: string
+      interrupt_before:
+        type: array
+        items:
+          type: string
+        description: "Nodes to interrupt before (human-in-the-loop)"
+      interrupt_after:
+        type: array
+        items:
+          type: string
+        description: "Nodes to interrupt after"
+
+  LangChainCallbackConfig:
+    type: object
+    required:
+      - type
+    properties:
+      type:
+        type: string
+        enum:
+          - langchain_tracer
+          - langsmith
+          - stdout
+          - file
+          - opentelemetry
+          - phoenix
+          - wandb
+          - mlflow
+          - custom
+        description: "Callback handler type"
+      config:
+        type: object
+        additionalProperties: true
+        description: "Handler-specific configuration"
+      events:
+        type: array
+        items:
+          type: string
+          enum:
+            - on_llm_start
+            - on_llm_end
+            - on_llm_error
+            - on_chain_start
+            - on_chain_end
+            - on_chain_error
+            - on_tool_start
+            - on_tool_end
+            - on_tool_error
+            - on_agent_action
+            - on_agent_finish
+            - on_retriever_start
+            - on_retriever_end
+            - on_text
+            - on_retry
+        description: "Events to handle (empty = all)"
+```
+
+## Bidirectional Mapping Tables
+
+### 1. LCEL Chains to OSSA Workflows
+
+| LangChain Construct | OSSA Equivalent | Notes |
+|---------------------|-----------------|-------|
+| `prompt \| llm \| parser` | `Workflow.steps[]` with sequential `Task` refs | Pipe operator maps to step dependencies |
+| `RunnableSequence` | `Workflow` with ordered `steps` | Each runnable becomes a step |
+| `RunnableParallel` | `Workflow.steps[].kind: Parallel` | Parallel execution group |
+| `RunnableBranch` | `Workflow.steps[].kind: Conditional` | Conditional branching |
+| `RunnableLambda` | `Task` with `execution.type: deterministic` | Pure function wrapper |
+| `RunnablePassthrough` | `Task` with identity transform | Input passthrough |
+| `chain.with_fallbacks()` | `Workflow.error_handling.on_failure: fallback` | Error fallback chain |
+| `chain.batch()` | `Task.batch.enabled: true` | Batch processing |
+| `chain.astream()` | `runtime.transport: async` | Streaming execution |
+| `chain.invoke()` | Standard workflow execution | Synchronous invocation |
+
+### 2. LangGraph State Machines to OSSA Workflows
+
+| LangGraph Construct | OSSA Equivalent | Notes |
+|---------------------|-----------------|-------|
+| `StateGraph` | `kind: Workflow` | Workflow with state context |
+| `graph.add_node()` | `Workflow.steps[]` | Each node is a step |
+| `graph.add_edge()` | `steps[].depends_on` | Explicit dependencies |
+| `graph.add_conditional_edges()` | `steps[].kind: Conditional` with `branches` | Conditional routing |
+| `START` | First step (no `depends_on`) | Entry point |
+| `END` | Step with no dependents | Terminal state |
+| `MemorySaver` | `spec.state.persistence` | State checkpointing |
+| `graph.compile()` | Workflow validation | Compile-time checks |
+| `interrupt_before` | Human-in-loop approval | `access.requires_approval` |
+| `state.messages` | `spec.state.schema.messages` | Message history |
+| `state.update` | `steps[].output.to` | State updates |
+
+### 3. Tool/Function Binding to OSSA Capabilities
+
+| LangChain Construct | OSSA Equivalent | Notes |
+|---------------------|-----------------|-------|
+| `@tool` decorator | `spec.tools[]` | Tool definition |
+| `Tool(name, func, description)` | `Tool` definition | Explicit tool |
+| `StructuredTool` | `Tool` with `parameters` schema | Typed parameters |
+| `BaseTool` subclass | `Tool` with `implementation` | Custom tool class |
+| `create_retriever_tool()` | `Tool` + `extensions.mcp.resources` | Retrieval tool |
+| `bind_tools()` | `spec.tools` assignment | Bind tools to agent |
+| `tool_choice` | `llm.tool_calling.mode` | Tool selection mode |
+| `ToolExecutor` | `runtime.bindings` | Execution binding |
+| `ToolMessage` | Messaging extension | Tool result message |
+
+### 4. Memory to OSSA State
+
+| LangChain Memory | OSSA State Config | Notes |
+|------------------|-------------------|-------|
+| `ConversationBufferMemory` | `state.schema: {messages: array}` | Full history |
+| `ConversationBufferWindowMemory(k=5)` | `state.history.window_size: 5` | Sliding window |
+| `ConversationSummaryMemory` | `state.summarization.enabled: true` | Summarized history |
+| `VectorStoreRetrieverMemory` | `state.vector_store` + retriever tool | Semantic search |
+| `EntityMemory` | `state.entities` schema | Entity extraction |
+| `CombinedMemory` | Multiple state schemas | Combined approach |
+| `memory.load_memory_variables()` | `state.load()` | State retrieval |
+| `memory.save_context()` | `state.save()` | State persistence |
+| `memory.clear()` | `state.clear()` | State reset |
+
+### 5. LangChain Agents to OSSA Agent Kind
+
+| LangChain Agent | OSSA Agent Config | Notes |
+|-----------------|-------------------|-------|
+| `create_react_agent()` | `type: specialist`, ReAct prompts | Reasoning + Acting |
+| `create_openai_functions_agent()` | `llm.tool_calling.format: openai_functions` | Function calling |
+| `create_openai_tools_agent()` | `llm.tool_calling.format: openai_tools` | Tool calling |
+| `create_xml_agent()` | `llm.tool_calling.format: xml` | XML format tools |
+| `create_structured_chat_agent()` | Structured output schema | Structured chat |
+| `create_tool_calling_agent()` | `llm.tool_calling.enabled: true` | Generic tool calling |
+| `AgentExecutor` | OSSA runtime execution | Agent execution loop |
+| `agent.astream_events()` | `observability.streaming: true` | Event streaming |
+| `max_iterations` | `constraints.max_iterations` | Iteration limit |
+| `handle_parsing_errors` | `constraints.error_handling` | Error recovery |
+
+### 6. Callbacks to OSSA Observability
+
+| LangChain Callback | OSSA Observability | Notes |
+|--------------------|---------------------|-------|
+| `StdOutCallbackHandler` | `observability.logging.level: debug` | Console output |
+| `FileCallbackHandler` | `observability.logging.file` | File logging |
+| `LangChainTracer` | `observability.tracing.enabled: true` | Distributed tracing |
+| `LangSmithCallbackHandler` | External service integration | LangSmith platform |
+| `OpenTelemetryCallbackHandler` | `observability.otlp` | OpenTelemetry export |
+| `ArizePhoenixCallbackHandler` | `observability.phoenix` | Phoenix observability |
+| `WandbCallbackHandler` | `observability.wandb` | Weights & Biases |
+| `on_llm_start` | `observability.events.llm_start` | LLM invocation start |
+| `on_chain_end` | `observability.events.chain_end` | Chain completion |
+| `on_tool_error` | `observability.events.tool_error` | Tool execution error |
+
+### 7. Runnables to OSSA Task Kind
+
+| LangChain Runnable | OSSA Task Config | Notes |
+|--------------------|------------------|-------|
+| `Runnable` (base) | `kind: Task` | Base task |
+| `RunnableLambda` | `execution.type: deterministic` | Pure function |
+| `RunnableGenerator` | `execution.type: generator` | Streaming output |
+| `RunnableRetry` | `error_handling.retry` | Retry logic |
+| `RunnableWithFallbacks` | `error_handling.fallback_task` | Fallback chain |
+| `RunnableBinding` | `runtime.bindings` | Runtime binding |
+| `RunnableConfigurableFields` | `runtime.configurable` | Runtime config |
+| `RunnableConfigurableAlternatives` | Multiple task variants | A/B testing |
+| `runnable.invoke()` | Task execution | Synchronous |
+| `runnable.ainvoke()` | Async task execution | Asynchronous |
+| `runnable.batch()` | `batch.enabled: true` | Batch processing |
+| `runnable.stream()` | Streaming execution | Token streaming |
+
+## Example Manifests
+
+### 1. ReAct Agent with Tools
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: react-research-agent
+  version: 1.0.0
+  description: Research agent using ReAct pattern with web search and calculator
+
+spec:
+  role: |
+    You are a research assistant that uses the ReAct pattern.
+    Think step-by-step, use tools when needed, and provide accurate answers.
+
+  llm:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    temperature: 0.1
+
+  tools:
+    - name: web_search
+      description: Search the web for current information
+      parameters:
+        type: object
+        properties:
+          query:
+            type: string
+            description: Search query
+        required: [query]
+
+    - name: calculator
+      description: Perform mathematical calculations
+      parameters:
+        type: object
+        properties:
+          expression:
+            type: string
+            description: Mathematical expression to evaluate
+        required: [expression]
+
+  constraints:
+    max_iterations: 15
+    timeout_seconds: 120
+
+  state:
+    persistence:
+      type: redis
+      connection_string: ${REDIS_URL}
+    schema:
+      type: object
+      properties:
+        messages:
+          type: array
+          items:
+            type: object
+            properties:
+              role:
+                type: string
+              content:
+                type: string
+        intermediate_steps:
+          type: array
+
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+    logging:
+      level: info
+
+extensions:
+  langchain:
+    enabled: true
+    version: "0.3.0"
+    agent_type: react
+    agent_config:
+      handle_parsing_errors: true
+      max_iterations: 15
+      return_intermediate_steps: true
+    memory_type: conversation_buffer
+    memory_config:
+      max_token_limit: 4000
+    callbacks:
+      - type: langsmith
+        config:
+          project_name: research-agent
+      - type: opentelemetry
+        config:
+          endpoint: ${OTEL_EXPORTER_ENDPOINT}
+```
+
+### 2. LangGraph Workflow with Conditional Edges
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Workflow
+metadata:
+  name: content-moderation-graph
+  version: 1.0.0
+  description: Content moderation workflow using LangGraph state machine
+
+spec:
+  inputs:
+    type: object
+    properties:
+      content:
+        type: string
+        description: Content to moderate
+      content_type:
+        type: string
+        enum: [text, image, video]
+    required: [content, content_type]
+
+  outputs:
+    type: object
+    properties:
+      approved:
+        type: boolean
+      flags:
+        type: array
+        items:
+          type: string
+      confidence:
+        type: number
+
+  steps:
+    - id: classify
+      name: Content Classification
+      kind: Task
+      ref: ./tasks/classify-content.yaml
+      input:
+        content: ${{ workflow.input.content }}
+        content_type: ${{ workflow.input.content_type }}
+
+    - id: route
+      name: Route by Classification
+      kind: Conditional
+      condition: ${{ steps.classify.output.risk_level }}
+      branches:
+        - condition: ${{ steps.classify.output.risk_level == 'low' }}
+          steps:
+            - id: auto_approve
+              kind: Task
+              ref: ./tasks/auto-approve.yaml
+        - condition: ${{ steps.classify.output.risk_level == 'medium' }}
+          steps:
+            - id: detailed_review
+              kind: Agent
+              ref: ./agents/content-reviewer.yaml
+        - condition: ${{ steps.classify.output.risk_level == 'high' }}
+          steps:
+            - id: human_review
+              kind: Task
+              ref: ./tasks/queue-human-review.yaml
+
+    - id: finalize
+      name: Finalize Decision
+      kind: Task
+      ref: ./tasks/finalize-moderation.yaml
+      depends_on: [route]
+
+  context:
+    variables:
+      moderation_policy_version: "2.1"
+
+  error_handling:
+    on_failure: notify
+    notification:
+      channels: [slack]
+
+extensions:
+  langchain:
+    enabled: true
+    version: "0.3.0"
+    graphs:
+      - name: moderation-graph
+        state_schema:
+          type: object
+          properties:
+            content:
+              type: string
+            risk_level:
+              type: string
+              enum: [low, medium, high]
+            flags:
+              type: array
+            decision:
+              type: string
+        nodes:
+          - id: classify
+            type: function
+            handler: "moderation.classify_content"
+            ossa_ref: ./tasks/classify-content.yaml
+          - id: auto_approve
+            type: function
+            handler: "moderation.auto_approve"
+          - id: detailed_review
+            type: agent
+            ossa_ref: ./agents/content-reviewer.yaml
+          - id: human_review
+            type: human_in_loop
+            handler: "moderation.queue_human"
+          - id: finalize
+            type: function
+            handler: "moderation.finalize"
+        edges:
+          - from: START
+            to: classify
+          - from: classify
+            to: route
+            condition: "route_by_risk"
+            condition_map:
+              low: auto_approve
+              medium: detailed_review
+              high: human_review
+          - from: auto_approve
+            to: finalize
+          - from: detailed_review
+            to: finalize
+          - from: human_review
+            to: finalize
+          - from: finalize
+            to: END
+        checkpointer:
+          type: postgres
+          connection_string: ${DATABASE_URL}
+        interrupt_before:
+          - human_review
+```
+
+### 3. LCEL Chain as OSSA Task
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Task
+metadata:
+  name: summarization-chain
+  version: 1.0.0
+  description: Document summarization using LCEL chain
+
+spec:
+  execution:
+    type: deterministic
+    runtime: python
+    entrypoint: chains.summarization:run_chain
+    timeout_seconds: 60
+
+  capabilities:
+    - summarize_text
+    - extract_entities
+
+  input:
+    type: object
+    properties:
+      document:
+        type: string
+        description: Document text to summarize
+      max_length:
+        type: integer
+        default: 500
+        description: Maximum summary length
+      style:
+        type: string
+        enum: [concise, detailed, bullet_points]
+        default: concise
+    required: [document]
+
+  output:
+    type: object
+    properties:
+      summary:
+        type: string
+      key_points:
+        type: array
+        items:
+          type: string
+      entities:
+        type: array
+        items:
+          type: object
+          properties:
+            name:
+              type: string
+            type:
+              type: string
+
+  batch:
+    enabled: true
+    parallelism: 5
+    chunk_size: 10
+
+  error_handling:
+    on_error: retry
+    error_mapping:
+      rate_limit_exceeded: retry
+      context_length_exceeded: fail
+
+  observability:
+    logging:
+      level: info
+    metrics:
+      enabled: true
+      custom_labels:
+        chain_type: summarization
+
+extensions:
+  langchain:
+    enabled: true
+    version: "0.3.0"
+    chains:
+      - name: summarization
+        type: sequential
+        lcel_expression: "prompt | llm | parser"
+        components:
+          - type: prompt
+            ref: prompts/summarization.yaml
+            config:
+              input_variables: [document, max_length, style]
+          - type: llm
+            ref: ${LLM_MODEL:-claude-sonnet-4-20250514}
+            config:
+              temperature: 0.3
+          - type: parser
+            ref: parsers/summary_output
+        input_schema:
+          type: object
+          properties:
+            document:
+              type: string
+            max_length:
+              type: integer
+            style:
+              type: string
+        output_schema:
+          type: object
+          properties:
+            summary:
+              type: string
+            key_points:
+              type: array
+        fallback:
+          chain_ref: chains/simple_summarization
+          exceptions:
+            - OutputParserException
+    runnable_config:
+      max_concurrency: 10
+      recursion_limit: 5
+      tags:
+        - summarization
+        - production
+      metadata:
+        version: "1.0"
+```
+
+### 4. Vector Store Memory Agent
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: knowledge-assistant
+  version: 1.0.0
+  description: Knowledge assistant with vector store memory
+
+spec:
+  role: |
+    You are a knowledge assistant with access to a vector store of documents.
+    Use the retrieved context to answer questions accurately.
+    If you don't find relevant information, say so clearly.
+
+  llm:
+    provider: openai
+    model: gpt-4o
+    temperature: 0.2
+
+  tools:
+    - name: search_knowledge_base
+      description: Search the knowledge base for relevant documents
+      parameters:
+        type: object
+        properties:
+          query:
+            type: string
+            description: Search query
+          k:
+            type: integer
+            default: 5
+            description: Number of results
+        required: [query]
+
+  state:
+    schema:
+      type: object
+      properties:
+        messages:
+          type: array
+        retrieved_documents:
+          type: array
+        session_context:
+          type: object
+    persistence:
+      type: postgres
+      connection_string: ${DATABASE_URL}
+
+  constraints:
+    max_iterations: 10
+    timeout_seconds: 90
+
+extensions:
+  langchain:
+    enabled: true
+    version: "0.3.0"
+    agent_type: openai_tools
+    memory_type: vector_store
+    memory_config:
+      vector_store:
+        type: qdrant
+        collection_name: knowledge_base
+        embedding_model: text-embedding-3-small
+        connection_string: ${QDRANT_URL}
+      max_token_limit: 8000
+    agent_config:
+      max_iterations: 10
+      handle_parsing_errors: true
+      return_intermediate_steps: false
+    callbacks:
+      - type: phoenix
+        config:
+          project_name: knowledge-assistant
+        events:
+          - on_retriever_start
+          - on_retriever_end
+          - on_llm_start
+          - on_llm_end
+```
+
+### 5. Multi-Agent Conversation with OpenAI Functions
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Workflow
+metadata:
+  name: multi-agent-conversation
+  version: 1.0.0
+  description: Multi-agent conversation using LangGraph
+
+spec:
+  steps:
+    - id: coordinator
+      kind: Agent
+      ref: ./agents/coordinator.yaml
+      input:
+        task: ${{ workflow.input.task }}
+
+    - id: research_agent
+      kind: Agent
+      ref: ./agents/researcher.yaml
+      condition: ${{ steps.coordinator.output.needs_research }}
+      input:
+        query: ${{ steps.coordinator.output.research_query }}
+
+    - id: writing_agent
+      kind: Agent
+      ref: ./agents/writer.yaml
+      depends_on: [research_agent]
+      condition: ${{ steps.coordinator.output.needs_writing }}
+      input:
+        research: ${{ steps.research_agent.output.findings }}
+        style: ${{ workflow.input.style }}
+
+    - id: review_agent
+      kind: Agent
+      ref: ./agents/reviewer.yaml
+      depends_on: [writing_agent]
+      input:
+        content: ${{ steps.writing_agent.output.draft }}
+
+  context:
+    variables:
+      conversation_id: ${{ uuid() }}
+
+extensions:
+  langchain:
+    enabled: true
+    version: "0.3.0"
+    graphs:
+      - name: multi-agent-graph
+        state_schema:
+          type: object
+          properties:
+            messages:
+              type: array
+              description: Shared message history
+            current_agent:
+              type: string
+            task_status:
+              type: string
+              enum: [pending, researching, writing, reviewing, complete]
+        nodes:
+          - id: coordinator
+            type: agent
+            ossa_ref: ./agents/coordinator.yaml
+          - id: research_agent
+            type: agent
+            ossa_ref: ./agents/researcher.yaml
+          - id: writing_agent
+            type: agent
+            ossa_ref: ./agents/writer.yaml
+          - id: review_agent
+            type: agent
+            ossa_ref: ./agents/reviewer.yaml
+        edges:
+          - from: START
+            to: coordinator
+          - from: coordinator
+            to: route
+            condition: "route_to_agent"
+            condition_map:
+              research: research_agent
+              write: writing_agent
+              review: review_agent
+              done: END
+          - from: research_agent
+            to: coordinator
+          - from: writing_agent
+            to: coordinator
+          - from: review_agent
+            to: coordinator
+        checkpointer:
+          type: redis
+          connection_string: ${REDIS_URL}
+    memory_type: conversation_buffer
+    memory_config:
+      max_token_limit: 16000
+    callbacks:
+      - type: langsmith
+        config:
+          project_name: multi-agent-conversation
+```
+
+## Implementation Notes
+
+### Converting LangChain to OSSA
+
+1. **Chains to Workflows**:
+   - Each pipe operator (`|`) becomes a step dependency
+   - `RunnableParallel` becomes `kind: Parallel` step
+   - `RunnableBranch` becomes `kind: Conditional` with branches
+
+2. **LangGraph to Workflow**:
+   - `StateGraph` state schema maps to `spec.context.variables`
+   - Node handlers become Task or Agent refs
+   - Conditional edges use OSSA expression syntax
+   - Checkpointer maps to state persistence
+
+3. **Memory to State**:
+   - Memory variables become state schema properties
+   - Window size maps to `state.history.window_size`
+   - Vector store memory uses retriever tool + state
+
+4. **Callbacks to Observability**:
+   - Event handlers map to OSSA observability events
+   - Tracers integrate via OpenTelemetry
+   - Custom callbacks use webhook or custom handlers
+
+### Converting OSSA to LangChain
+
+1. **Workflow to LCEL**:
+   - Sequential steps become pipe chains
+   - Parallel steps use `RunnableParallel`
+   - Conditional steps use `RunnableBranch`
+
+2. **Agent to LangChain Agent**:
+   - Map agent type to appropriate create_*_agent function
+   - Tools become `@tool` decorated functions
+   - Constraints become AgentExecutor parameters
+
+3. **State to Memory**:
+   - State schema drives memory type selection
+   - Persistence config maps to memory backend
+   - Window size determines BufferWindow k value
+
+## Validation
+
+Validate LangChain extension configuration:
+
+```bash
+# Validate manifest with LangChain extension
+ossa validate manifest.yaml --extension langchain
+
+# Check LangGraph graph definition
+ossa validate manifest.yaml --check-graphs
+
+# Verify callback configuration
+ossa validate manifest.yaml --check-callbacks
+```
+
+## Best Practices
+
+1. **Version Compatibility**: Always specify `version` to ensure LangChain API compatibility
+2. **Memory Selection**: Choose memory type based on use case - buffer for short conversations, vector store for knowledge retrieval
+3. **Callback Efficiency**: Only subscribe to needed events to reduce overhead
+4. **State Schema**: Define explicit state schemas for type safety
+5. **Error Handling**: Configure fallbacks for production chains
+6. **Observability**: Enable tracing for debugging and monitoring
+7. **Batch Processing**: Use batch configuration for high-throughput scenarios
+
+## References
+
+- [LangChain Documentation](https://python.langchain.com/docs/)
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+- [OSSA v0.3.3 Specification](../ossa-0.3.3.schema.json)
+- [OSSA Workflow Specification](../UNIFIED-SCHEMA.md)
+- [OSSA Observability Extension](./observability.md)