Reconcile MDA docs with public beta changes

pipeline/core/builder.py

@@ -115,6 +115,9 @@ def build_all(self) -> None:
         logger.debug("Building LangSmith content...")
         self._build_unversioned_content("langsmith", "langsmith")
 
+        logger.debug("Building Managed Deep Agents language variants...")
+        self._build_managed_deep_agents_versions()
+
         # Copy shared files (docs.json, images, etc.)
         logger.debug("Copying shared files...")
         self._copy_shared_files()
@@ -202,6 +205,27 @@ def rewrite_link(match: re.Match) -> str:
         pattern = r'(\[.*?\]\(|\bhref="|")(/oss/[^")\s]+)([")\s])'
         return re.sub(pattern, rewrite_link, content)
 
+    def _rewrite_managed_deep_agents_links(
+        self, content: str, target_language: str | None
+    ) -> str:
+        """Rewrite Managed Deep Agents links to the target language route."""
+        if not target_language:
+            return content
+
+        language = self.language_url_names[target_language]
+
+        def rewrite_link(match: re.Match) -> str:
+            prefix, url, suffix = match.groups()
+            relative_url = url.removeprefix("/langsmith/")
+            return f"{prefix}/langsmith/{language}/{relative_url}{suffix}"
+
+        pattern = (
+            r'(\[.*?\]\(|\bhref="|")'
+            r'(/langsmith/managed-deep-agents[^"\)\s]*)'
+            r'(["\)\s])'
+        )
+        return re.sub(pattern, rewrite_link, content)
+
     def _add_suggested_edits_link(self, content: str, input_path: Path) -> str:
         """Add 'Edit Source' link to the end of markdown content.
 
@@ -315,8 +339,8 @@ def _process_markdown_content(
                     content, target_language
                 )
 
-            # Then rewrite /oss/ links to include language
-            return self._rewrite_oss_links(content, target_language)
+            content = self._rewrite_oss_links(content, target_language)
+            return self._rewrite_managed_deep_agents_links(content, target_language)
 
         except Exception:
             logger.exception("Failed to process markdown content from %s", file_path)
@@ -450,6 +474,41 @@ def _build_oss_file(self, file_path: Path, relative_path: Path) -> None:
         if self._build_single_file_to_path(file_path, js_output, "js"):
             logger.debug("Built JavaScript version: oss/javascript/%s", oss_relative)
 
+    def is_managed_deep_agents_file(self, file_path: Path) -> bool:
+        """Return whether a source file is a Managed Deep Agents page."""
+        try:
+            relative_path = file_path.absolute().relative_to(self.src_dir.absolute())
+        except ValueError:
+            return False
+        return (
+            relative_path.parent == Path("langsmith")
+            and relative_path.name.startswith("managed-deep-agents")
+            and relative_path.suffix.lower() in {".md", ".mdx"}
+        )
+
+    def _build_managed_deep_agents_variants(self, file_path: Path) -> None:
+        """Build Python and JavaScript routes for a Managed Deep Agents page."""
+        relative_path = file_path.absolute().relative_to(self.src_dir.absolute())
+        langsmith_relative = relative_path.relative_to("langsmith")
+        for language, output_name in self.language_url_names.items():
+            output_path = (
+                self.build_dir / "langsmith" / output_name / langsmith_relative
+            )
+            if self._build_single_file_to_path(file_path, output_path, language):
+                logger.debug(
+                    "Built Managed Deep Agents %s version: %s",
+                    output_name,
+                    langsmith_relative,
+                )
+
+    def _build_managed_deep_agents_versions(self) -> None:
+        """Build language-specific routes for all Managed Deep Agents pages."""
+        langsmith_dir = self.src_dir / "langsmith"
+        if not langsmith_dir.exists():
+            return
+        for file_path in langsmith_dir.glob("managed-deep-agents*.mdx"):
+            self._build_managed_deep_agents_variants(file_path)
+
     def _build_unversioned_file(self, file_path: Path, relative_path: Path) -> None:
         """Build an unversioned file (langsmith).
 
@@ -460,6 +519,8 @@ def _build_unversioned_file(self, file_path: Path, relative_path: Path) -> None:
         output_path = self.build_dir / relative_path
         if self._build_single_file_to_path(file_path, output_path, "python"):
             logger.debug("Built: %s", relative_path)
+        if self.is_managed_deep_agents_file(file_path):
+            self._build_managed_deep_agents_variants(file_path)
 
     def _build_shared_file(self, file_path: Path, relative_path: Path) -> None:
         """Build a shared file (images, docs.json, JS/CSS files).
@@ -561,7 +622,10 @@ def _build_file_with_progress(self, file_path: Path, pbar: tqdm) -> bool:
         if file_path.suffix.lower() in self.copy_extensions:
             # Handle markdown files with preprocessing
             if file_path.suffix.lower() in {".md", ".mdx"}:
-                self._process_markdown_file(file_path, output_path)
+                if self.is_managed_deep_agents_file(file_path):
+                    self._build_unversioned_file(file_path, relative_path)
+                else:
+                    self._process_markdown_file(file_path, output_path)
                 return True
             shutil.copy2(file_path, output_path)
             return True
@@ -1153,10 +1217,6 @@ def _process_snippet_markdown_file(
             with input_path.open("r", encoding="utf-8") as f:
                 content = f.read()
 
-            processed_content = preprocess_markdown(
-                content, input_path, target_language=None
-            )
-
             if input_path.suffix.lower() == ".md":
                 output_path = output_path.with_suffix(".mdx")
 
@@ -1166,14 +1226,26 @@ def _process_snippet_markdown_file(
             )
 
             for lang_key, lang_name in self.language_url_names.items():
-                lang_content = self._rewrite_oss_links(processed_content, lang_key)
+                lang_content = preprocess_markdown(
+                    content, input_path, target_language=lang_key
+                )
+                lang_content = self._rewrite_oss_links(lang_content, lang_key)
+                lang_content = self._rewrite_managed_deep_agents_links(
+                    lang_content, lang_key
+                )
                 lang_output = snippets_root / lang_name / relative_snippet
                 lang_output.parent.mkdir(parents=True, exist_ok=True)
                 with lang_output.open("w", encoding="utf-8") as f:
                     f.write(lang_content)
 
             # Default path: Python-prefixed absolute links for unversioned pages.
-            default_content = self._rewrite_oss_links(processed_content, "python")
+            default_content = preprocess_markdown(
+                content, input_path, target_language="python"
+            )
+            default_content = self._rewrite_oss_links(default_content, "python")
+            default_content = self._rewrite_managed_deep_agents_links(
+                default_content, "python"
+            )
             output_path.parent.mkdir(parents=True, exist_ok=True)
             with output_path.open("w", encoding="utf-8") as f:
                 f.write(default_content)

src/docs.json

@@ -206,8 +206,8 @@
                       {
                         "group": "Deployment",
                         "pages": [
-                          "langsmith/managed-deep-agents",
-                          {
+                          "langsmith/python/managed-deep-agents",
+                      {
                             "group": "Going to production",
                             "root": "oss/python/deepagents/going-to-production",
                             "pages": [
@@ -290,6 +290,52 @@
                       }
                     ]
                   },
+                  {
+                    "tab": "Managed Deep Agents",
+                    "pages": [
+                      {
+                        "group": "Get started",
+                        "tag": "BETA",
+                        "pages": [
+                          "langsmith/python/managed-deep-agents-overview",
+                          "langsmith/python/managed-deep-agents-quickstart",
+                          "langsmith/python/managed-deep-agents-project-structure"
+                        ]
+                      },
+                      {
+                        "group": "Agent definition",
+                        "pages": [
+                          "langsmith/python/managed-deep-agents-agent-definition",
+                          "langsmith/python/managed-deep-agents-instructions",
+                          "langsmith/python/managed-deep-agents-skills",
+                          "langsmith/python/managed-deep-agents-tools",
+                          "langsmith/python/managed-deep-agents-middleware",
+                          "langsmith/python/managed-deep-agents-memory",
+                          "langsmith/python/managed-deep-agents-sandboxes",
+                          "langsmith/python/managed-deep-agents-identity",
+                          {
+                            "group": "Channels",
+                            "expanded": false,
+                            "pages": [
+                              "langsmith/python/managed-deep-agents-channels",
+                              "langsmith/python/managed-deep-agents-channels-slack"
+                            ]
+                          },
+                          "langsmith/python/managed-deep-agents-schedules",
+                          "langsmith/python/managed-deep-agents-evals"
+                        ]
+                      },
+                      {
+                        "group": "Build and deploy",
+                        "pages": [
+                          "langsmith/python/managed-deep-agents-local-development",
+                          "langsmith/python/managed-deep-agents-tutorial",
+                          "langsmith/python/managed-deep-agents-deploy",
+                          "langsmith/python/managed-deep-agents-cli"
+                        ]
+                      }
+                    ]
+                  },
                   {
                     "tab": "LangChain",
                     "pages": [
@@ -712,7 +758,7 @@
                       {
                         "group": "Deployment",
                         "pages": [
-                          "langsmith/managed-deep-agents",
+                          "langsmith/javascript/managed-deep-agents",
                           {
                             "group": "Going to production",
                             "root": "oss/javascript/deepagents/going-to-production",
@@ -795,6 +841,52 @@
                       }
                     ]
                   },
+                  {
+                    "tab": "Managed Deep Agents",
+                    "pages": [
+                      {
+                        "group": "Get started",
+                        "tag": "BETA",
+                        "pages": [
+                          "langsmith/javascript/managed-deep-agents-overview",
+                          "langsmith/javascript/managed-deep-agents-quickstart",
+                          "langsmith/javascript/managed-deep-agents-project-structure"
+                        ]
+                      },
+                      {
+                        "group": "Agent definition",
+                        "pages": [
+                          "langsmith/javascript/managed-deep-agents-agent-definition",
+                          "langsmith/javascript/managed-deep-agents-instructions",
+                          "langsmith/javascript/managed-deep-agents-skills",
+                          "langsmith/javascript/managed-deep-agents-tools",
+                          "langsmith/javascript/managed-deep-agents-middleware",
+                          "langsmith/javascript/managed-deep-agents-memory",
+                          "langsmith/javascript/managed-deep-agents-sandboxes",
+                          "langsmith/javascript/managed-deep-agents-identity",
+                          {
+                            "group": "Channels",
+                            "expanded": false,
+                            "pages": [
+                              "langsmith/javascript/managed-deep-agents-channels",
+                              "langsmith/javascript/managed-deep-agents-channels-slack"
+                            ]
+                          },
+                          "langsmith/javascript/managed-deep-agents-schedules",
+                          "langsmith/javascript/managed-deep-agents-evals"
+                        ]
+                      },
+                      {
+                        "group": "Build and deploy",
+                        "pages": [
+                          "langsmith/javascript/managed-deep-agents-local-development",
+                          "langsmith/javascript/managed-deep-agents-tutorial",
+                          "langsmith/javascript/managed-deep-agents-deploy",
+                          "langsmith/javascript/managed-deep-agents-cli"
+                        ]
+                      }
+                    ]
+                  },
                   {
                     "tab": "LangChain",
                     "pages": [
@@ -1683,47 +1775,6 @@
                   }
                 ]
               },
-              {
-                "tab": "Managed Deep Agents",
-                "pages": [
-                  {
-                    "group": "Managed Deep Agents",
-                    "tag": "BETA",
-                    "pages": [
-                      "langsmith/managed-deep-agents-overview",
-                      "langsmith/managed-deep-agents-quickstart",
-                      "langsmith/managed-deep-agents-tutorial",
-                      "langsmith/managed-deep-agents-how-it-works",
-                      "langsmith/managed-deep-agents-identity",
-                      "langsmith/managed-deep-agents-memory",
-                      "langsmith/managed-deep-agents-evals",
-                      "langsmith/managed-deep-agents-tools",
-                      "langsmith/managed-deep-agents-middleware",
-                      {
-                        "group": "Connectors",
-                        "pages": [
-                          "langsmith/managed-deep-agents-connectors/index",
-                          "langsmith/managed-deep-agents-connectors/mcp",
-                          "langsmith/managed-deep-agents-connectors/langsmith",
-                          "langsmith/managed-deep-agents-connectors/github"
-                        ]
-                      },
-                      {
-                        "group": "Channels",
-                        "pages": [
-                          "langsmith/managed-deep-agents-channels/index",
-                          "langsmith/managed-deep-agents-channels/slack",
-                          "langsmith/managed-deep-agents-channels/github"
-                        ]
-                      },
-                      "langsmith/managed-deep-agents-schedules",
-                      "langsmith/managed-deep-agents-examples",
-                      "langsmith/managed-deep-agents-deploy",
-                      "langsmith/managed-deep-agents-cli"
-                    ]
-                  }
-                ]
-              },
               {
                 "tab": "Prompt & Context Hub",
                 "pages": [
@@ -2501,10 +2552,6 @@
       "source": "/langsmith/env-var",
       "destination": "/langsmith/env-var-cloud"
     },
-    {
-      "source": "/langsmith/managed-deep-agents-mcp",
-      "destination": "/langsmith/managed-deep-agents-connectors"
-    },
     {
       "source": "/langsmith/managed-deep-agents-invoke",
       "destination": "/langsmith/managed-deep-agents-overview"