Reconcile MDA docs with public beta changes - #5329
Merged
Harrison Chase (hwchase17) merged 27 commits intoAug 7, 2026
Merged
Conversation
docs(MDA): trim channels description to shipped providers
Adopt the dev80 identity vocabulary across the straight-terminology MDA pages, reconciled against managed-deepagents==0.5.0.dev80: - actor -> user, tenant -> organization - preset/.preset(...) -> define_identity()/defineIdentity() (scope-based) - scoping.memory -> scope.memory; thread/memory value "actor" -> "user" - LANGSMITH_TENANT_ID -> LANGCHAIN_WORKSPACE_ID; --tenant-id -> --workspace-id - headers X-MDA-Actor-Id -> X-MDA-User-Id, X-MDA-Tenant-Id -> X-MDA-Organization-Id - evals identity.json fixture: "actor"/"type" -> "user"/"kind":"person", "tenant" -> "organization", add "groups" (verified against dev80 identity schema) X-MDA-Ingress-Secret and MDA_INGRESS_SECRET are intentionally left literal (dev80 keeps these names). No API, route, or page-structure changes: the sandbox API change and channels->connectors content are deferred to later commits, so how-it-works keeps its Connectors section and deploy is untouched.
Update the existing connector pages to the managed-deepagents==0.5.0.dev80
authoring model and add the tool server integrations catalog. Verified
against the installed dev80 SDK source and the live project connectors/*.py.
- mcp: define_mcp_servers()/export const mcp -> connectors.mcp(mcp_servers={...})
with export const connector
- github: github.connector()/export default -> connectors.github(); reframe as
the two halves (tool server tools + sandbox); add the "Tools and the
installCLI rule" section and include_tools/exclude_tools options; keep the
detailed repositories field table
- langsmith: langsmith.connector(<builders>)/export default ->
connectors.langsmith(capabilities=[...]) with builders on
connectors.langsmith.* (route POST /connectors/langsmith/capabilities/{id}
unchanged); fix the trusted-backend header identifiers to X-MDA-User-Id /
X-MDA-Organization-Id (the SDK renamed these headers); preserve the literal
one_per_actor/onePerActor API field
- index: add the Integrations row, the "export const connector" note, and an
Integrations card
- integrations: new page for connectors.<provider>(...) tool server
integrations; the 26-entry catalog, include_tools/exclude_tools/
default_tool_timeout options, LANGSMITH_ENDPOINT/LANGCHAIN_WORKSPACE_ID
resolution, strict extra="forbid" schema, and MDA_TOOLSERVER_AGENT_ID all
verified against dev80
- docs.json: add connectors/integrations to the Connectors nav group
Channels links and the channels->connectors fold are deferred to later
commits, so existing /managed-deep-agents-channels/* links stay intact and
broken-links remains clean. Soft actor/tenant prose on connector pages is
left for the terminology reconciliation.
dev80 folds the former GitHub channel into connectors.github(events=[...])
on the same connector that does sandbox checkouts, so document webhooks
there instead of on a separate channel page.
- connectors/github.mdx: add a "Receive GitHub App webhooks" section built
on connectors.github(events=[{on, prompt, repositories, auto_reply}]) and
POST /connectors/github/events; reframe the intro as three halves (Tools,
Sandbox, Events); add event-filter, prompt-vs-instructions, protocol
diagram, handler options, required webhook secrets, App configuration, and
webhook troubleshooting. All protocol facts (HTTP 202, X-Hub-Signature-256,
X-GitHub-Delivery dedupe, source.provider "github", the GITHUB_* secret
names, MDA_INGRESS_SECRET loopback) verified against managed-deepagents
0.5.0.dev80.
- Delete channels/github.mdx (its content moved to the connector page).
- Repoint inbound links on connectors/index, channels/index, and cli to
/connectors/github (or its #receive-github-app-webhooks anchor).
- docs.json: remove the channels/github nav entry and add a redirect from
/langsmith/managed-deep-agents-channels/github to /connectors/github.
Slack channel and the channels overview remain until commits 4-5, so their
links are intentionally left in place. Broken-links stays clean: no link
targets the deleted page.
dev84 folds the former Slack channel into connectors.slack(...). Document Slack as a connector, replacing the manual Slack-app setup with the managed provisioning flow. - New connectors/slack.mdx: connectors.slack(on=[...], auto_reply, mention_behavior, filters, conversation, app, contribute_tools) and POST /connectors/slack/events. mda deploy creates and installs the Slack app through the workspace's LangSmith Slack connection, points its Events Request URL at /connectors/slack/events, and writes the bot token and signing secret onto the deployment, so no SLACK_BOT_TOKEN / SLACK_SIGNING_SECRET in .env. Document the app branding (name/description/icon/ background_color), triggers/scopes, options, the managed secrets set, and Connect-with-Slack. Provisioning flow and no-secrets-in-.env behavior verified against the managed-deepagents-sdk examples/slack README and connector examples; MDA_TRIGGER_SERVER_URL confirmed absent in dev84. - Delete channels/slack.mdx. - Repoint inbound links on channels/index, cli, identity, and schedules to /connectors/slack. - docs.json: add connectors/slack to the Connectors nav group, remove the channels/slack entry, and add a redirect from /langsmith/managed-deep-agents-channels/slack to /connectors/slack. The channels overview (index) folds into connectors/index in commit 5; its remaining channels-model prose is intentionally left for that commit. Broken-links stays clean: no link targets the deleted page.
Complete the channels->connectors fold. The GitHub and Slack channels now
live on their connector pages (commits 3-4), so the standalone channels
overview and its nav group are no longer needed.
- connectors/index.mdx: add a "Provider events and messaging" section
(Slack Events + GitHub webhooks on POST /connectors/{name}/events, signature
verification, identity stamps, auto-reply, and scope-based threading with
define_identity(scope={"threads": "conversation"})); update "Choose the
right integration" to point at the Slack/GitHub connectors instead of a
channels page.
- Delete channels/index.mdx (and the now-empty channels/ directory).
- docs.json: remove the Channels nav group; add redirects from
/managed-deep-agents-channels and /managed-deep-agents-channels/index to
/connectors.
- Repoint remaining inbound links to /connectors on cli, identity, tutorial,
and the shared next-steps snippet. In deploy and how-it-works, also
reconcile stale channels prose: the /channels/{name}/events routes become
/connectors/{name}/events, and the deploy secrets note reflects dev84's
managed Slack app provisioning.
Broken-links stays clean: no link targets the deleted page. CLI reconciliation
is the remaining commit.
Final channels->connectors reconciliation for the CLI reference, verified
against managed-deepagents==0.5.0.dev84 and the managed-deepagents-sdk crate.
- Rename the deploy workspace flag/env to --workspace-id / LANGSMITH_WORKSPACE_ID
(LANGSMITH_TENANT_ID / --tenant-id are removed in dev84); update the auth
section, the deploy flag table, the reserved-variables note, and the deploy
steps.
- Document mda init --scope (user, shared-conversations, organization, agent,
none), which scaffolds the identity declaration.
- Rewrite the Connectors section: connectors export a named `connector`; add
Integrations and Slack; note that Slack/GitHub provider events mount
POST /connectors/{name}/events and that mda deploy provisions the Slack app.
- Remove the Channels section (folded into Connectors) and drop "channel" from
the authoring-APIs sentence.
- Clean identity vocabulary (drop `.preset(...)` and "presets/ingress").
- project-layout snippet: replace channels/* with connectors/slack, fold GitHub
webhooks into connectors/github, prefix every connector line with connectors/,
and align the comment column.
dev84 ships `mda connect`, which scaffolds a connector and completes its workspace OAuth from the terminal instead of the LangSmith Integrations UI. Behavior and flags verified against the managed-deepagents-sdk crate (crates/mda/src/connect) and a CLI recording of the flow. - cli.mdx: add a "Connect integrations" section (the --list catalog with the oauth/secret/none/deploy AUTH types and their STATUS, the connect-by-name scaffold + browser OAuth flow, and the --list/--check/--revoke/--json/--yes flags) plus a command-overview row. - integrations.mdx: add a "Connect from the CLI" subsection offering mda connect as an alternative to the manual LangSmith UI step. - connectors/index.mdx: mention mda connect and mda connect --list. Slack stays deploy-owned (AUTH "deploy", STATUS "via mda deploy"); secret-based integrations still take a workspace API key in LangSmith. Text-only for now; a CLI recording can be added later.
## Overview <!-- Brief description of what documentation is being added/updated --> ## Type of change **Type:** [Replace with: New documentation page / Update existing documentation / Fix typo/bug/link/formatting / Remove outdated content / Other] ## Related issues/PRs <!-- Link to related issues, feature PRs, or discussions (if applicable) To automatically close an issue when this PR is merged, use closing keywords: - "closes #123" or "fixes #123" or "resolves #123" For regular references without auto-closing, just use: - "#123" or "See issue #123" Examples: - closes #456 (will auto-close issue #456 when PR is merged) - See #789 for context (will reference but not auto-close issue #789) --> - GitHub issue: - Feature PR: <!-- For LangChain employees, if applicable: --> - Linear issue: - Slack thread: ## Checklist <!-- Put an 'x' in all boxes that apply --> - [ ] I have read the [contributing guidelines](README.md), including the [language policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy) - [ ] I have tested my changes locally using `docs dev` - [ ] All code examples have been tested and work correctly - [ ] I have used **root relative** paths for internal links - [ ] I have updated navigation in `src/docs.json` if needed (Internal team members only / optional): Create a preview deployment as necessary using the [Create Preview Branch workflow](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) ## Additional notes <!-- Any other information that would be helpful for reviewers -->
Update the Managed Deep Agents identity docs for the current public-beta scope model: identity now controls memory and credentials, while threads are always user-owned. Remove the old interactive scope explorer because it generated unsupported threads and organization scope declarations. Also update related memory, evals, CLI, deploy, overview, tools, tutorial, and LangSmith connector references so examples no longer mention organization-scoped identity, organization-scoped memory, or X-MDA-Organization-Id.
Florence Morris (fjmorris)
requested a review
from Christian Bromann (christian-bromann)
August 5, 2026 16:51
Rewrite the Slack connector page to match the public beta behavior: users bring their own Slack app, configure SLACK_SIGNING_SECRET and SLACK_BOT_TOKEN, and point Events API requests at /connectors/slack/events. Remove stale managed Slack app provisioning claims from the connector overview, CLI reference, and deploy docs. Also remove invalid Slack connector options and identity examples that used app branding, contribute_tools, and scope.threads.
Update the Managed Deep Agents integrations page to match the current public beta connector catalog from mda connect --list, including marketplace MCP connectors such as Notion, Cloudflare, Neon, Netlify, Prisma, Vanta, and Close. Refresh mda connect documentation for OAuth, secret-backed, credential-free, and BYOK Slack connector setup. Document current flags including --path, --secret, --oauth, --no-oauth, --open, and --workspace-id, and use LANGSMITH_WORKSPACE_ID for tool server routing.
Update the Managed Deep Agents CLI reference against the current public beta help output. Add the missing build, logs, and delete/destroy commands, document the current init flags, and fix the dev server browser flag. Remove stale CLI surface such as deploy --host-url and correct deploy/log/delete defaults to match the current mda command behavior verified against managed-deepagents==0.5.0.dev89.
Run a cross-page consistency pass over the Managed Deep Agents docs after the identity, Slack, integrations, and CLI updates. Remove stale channels terminology from the overview, replace tenant wording with organization wording, and clean up generic ingress language while preserving literal MDA_INGRESS_SECRET and X-MDA-Ingress-Secret names.
Remove the duplicate closing Card and CardGroup tags introduced during the identity cleanup so Mintlify can parse the Managed Deep Agents identity page. Validated with lint_prose, broken-links, and broken-links-with-anchors.
Update Managed Deep Agents Python install examples to use uv tool install --prerelease allow managed-deepagents instead of pip install --pre. Change Managed Deep Agents access and release-stage wording from private beta to public beta across the overview, deploy, middleware, quickstart, and shared prerequisite/beta-note snippets.
Florence Morris (fjmorris)
changed the base branch from
fjmorris/DOC-1403
to
main
August 5, 2026 22:39
| ### Support and feedback | ||
|
|
||
| Beta access includes direct support. The contact for bug reports and feature requests is included in the email you receive when access is granted. | ||
| Beta access includes direct support. Contact your LangChain team for bug reports and feature requests. |
Contributor
There was a problem hiding this comment.
what does this mean? your langchain team?
## Overview <!-- Brief description of what documentation is being added/updated --> ## Type of change **Type:** [Replace with: New documentation page / Update existing documentation / Fix typo/bug/link/formatting / Remove outdated content / Other] ## Related issues/PRs <!-- Link to related issues, feature PRs, or discussions (if applicable) To automatically close an issue when this PR is merged, use closing keywords: - "closes #123" or "fixes #123" or "resolves #123" For regular references without auto-closing, just use: - "#123" or "See issue #123" Examples: - closes #456 (will auto-close issue #456 when PR is merged) - See #789 for context (will reference but not auto-close issue #789) --> - GitHub issue: - Feature PR: <!-- For LangChain employees, if applicable: --> - Linear issue: - Slack thread: ## Checklist <!-- Put an 'x' in all boxes that apply --> - [ ] I have read the [contributing guidelines](README.md), including the [language policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy) - [ ] I have tested my changes locally using `docs dev` - [ ] All code examples have been tested and work correctly - [ ] I have used **root relative** paths for internal links - [ ] I have updated navigation in `src/docs.json` if needed (Internal team members only / optional): Create a preview deployment as necessary using the [Create Preview Branch workflow](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) ## Additional notes <!-- Any other information that would be helpful for reviewers -->
github-actions
Bot
added
docs-infra
javascript
python
Contributor
|
Mintlify preview branch generated: Site preview: https://langchain-5e9cc07a-preview-fjmorr-1786082951-7fc5d1b.mintlify.site Important Preview links may take a few minutes to start working while the deployment finishes. Changed documentation pages (preview deep links):
Only the top 5 changed markdown files by diff size are listed. |
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up cleanup branch for PR #5262, based on the current
fjmorris/DOC-1403branch. These commits were verified againstmanaged-deepagents==0.5.0.dev89.Commit 1 updates the Managed Deep Agents docs to match the public beta identity model: identity scopes memory and credentials, threads are always user-owned, and organization-scoped identity/memory is no longer documented. It removes the outdated identity scope explorer and updates related MDA docs and snippets.
Commit 2 updates the Slack connector docs for BYOK app setup: users bring their own Slack app, configure
SLACK_SIGNING_SECRETandSLACK_BOT_TOKEN, and point Events API requests at/connectors/slack/events. It removes stale managed Slack app provisioning claims from the Slack connector page, connector overview, CLI reference, and deploy docs.Commit 3 refreshes the integrations catalog and
mda connectdocs for the current public beta behavior: the catalog now matchesmda connect --list, includes marketplace MCP connectors such as Notion, Cloudflare, Neon, Netlify, Prisma, Vanta, and Close, and documents OAuth, secret-backed, credential-free, and BYOK Slack setup. It also updates the CLI flag table and usesLANGSMITH_WORKSPACE_IDfor tool server routing.Commit 4 reconciles the CLI reference with the current public beta command surface: it adds
mda build,mda logs, andmda delete/mda destroy, documents currentmda initflags, fixesmda dev --no-browser, removes stalemda deploy --host-url, and corrects deploy/log/delete defaults.Commit 5 runs a cross-page consistency cleanup after the identity, Slack, integrations, and CLI updates: it removes stale channels terminology from the overview, replaces tenant wording with organization wording, and cleans up generic ingress language while preserving literal
MDA_INGRESS_SECRETandX-MDA-Ingress-Secretnames.Commit 6 fixes the MDA identity page markup found during validation by removing duplicate closing
Card/CardGrouptags. Validation passed withmake lint_prose,make broken-links, andmake broken-links-with-anchors.Commit 7 updates the MDA install and release-stage wording: Python install examples now use
uv tool install --prerelease allow managed-deepagents, and access/release-stage copy now says public beta instead of private beta across the overview, deploy, middleware, quickstart, and shared snippets.