Updates of MDA doc set before Public Beta - #5262
Closed
Florence Morris (fjmorris) wants to merge 11 commits into
Closed
Updates of MDA doc set before Public Beta#5262Florence Morris (fjmorris) wants to merge 11 commits into
Florence Morris (fjmorris) wants to merge 11 commits into
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.
5 tasks
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.
Florence Morris (fjmorris)
requested a review
from Christian Bromann (christian-bromann)
August 3, 2026 20:19
Florence Morris (fjmorris)
marked this pull request as draft
August 3, 2026 20:19
## 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 -->
Contributor
|
Mintlify preview branch generated: Site preview: https://langchain-5e9cc07a-preview-fjmorr-1785940779-68b13f9.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. |
Contributor
Author
|
closing in favor of #5329 |
Harrison Chase (hwchase17)
added a commit
that referenced
this pull request
Aug 7, 2026
Follow-up cleanup branch for PR #5262, based on the current `fjmorris/DOC-1403` branch. These commits were verified against `managed-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_SECRET` and `SLACK_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 connect` docs for the current public beta behavior: the catalog now matches `mda 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 uses `LANGSMITH_WORKSPACE_ID` for tool server routing. Commit 4 reconciles the CLI reference with the current public beta command surface: it adds `mda build`, `mda logs`, and `mda delete` / `mda destroy`, documents current `mda init` flags, fixes `mda dev --no-browser`, removes stale `mda 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_SECRET` and `X-MDA-Ingress-Secret` names. Commit 6 fixes the MDA identity page markup found during validation by removing duplicate closing `Card` / `CardGroup` tags. Validation passed with `make lint_prose`, `make broken-links`, and `make 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. --------- Co-authored-by: Christian Bromann <git@bromann.dev> Co-authored-by: Harrison Chase <hw.chase.17@gmail.com> Co-authored-by: victorm-lc <victor@langchain.dev>
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
2 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.
Reconcile the Managed Deep Agents doc set to
managed-deepagents==0.5.0.dev84for public beta. Supersedes #5035. All API facts verified against the installed SDK.Provenance note: commits 1–3 were originally authored and verified against
0.5.0.dev80(see their commit messages). The target has since moved to0.5.0.dev84; every commit 1–3 fact was re-verified against dev84 and still holds unchanged (identity headers, evals fixture schema, theconnectors.*API surface,connectors.github(events=[...])routes/secrets, the LangSmith capability model, and the tool server integrations catalog). dev84 only adds capabilities (marketplace MCP connectors and additional identity connect providers), which are out of scope for commits 1–3. Commit 4 onward is authored against dev84.Commit 1 — terminology. Rename
actor→user,tenant→organization,ingress→auth, presets→define_identity()/defineIdentity()(scope-based),LANGSMITH_TENANT_ID→LANGCHAIN_WORKSPACE_ID, and theX-MDA-Actor-Id/X-MDA-Tenant-Idheaders across identity, memory, how-it-works, tools, evals, and quickstart.X-MDA-Ingress-SecretandMDA_INGRESS_SECRETintentionally kept literal.Commit 2 — connectors API. Move connector pages to the
connectors.*namespace (connectors.mcp,connectors.github,connectors.langsmith(capabilities=[...])) withexport const connector; add the GitHub tools/installCLIrule and a new tool server integrations catalog page.Commit 3 — GitHub webhooks fold. Fold the GitHub channel into
connectors.github(events=[...])on the connector page, delete the channels/github page, add a redirect, and repoint inbound links.Commit 4 — Slack connector. Add a new
connectors/slack.mdxonconnectors.slack(...)andPOST /connectors/slack/events, replacing the manual Slack-app setup with the managed provisioning flow:mda deploycreates and installs the Slack app through the workspace's LangSmith Slack connection and writes the bot token and signing secret onto the deployment (noSLACK_BOT_TOKEN/SLACK_SIGNING_SECRETin.env). Document theappbranding, triggers/scopes, options, and Connect-with-Slack. Delete the channels/slack page, add a redirect, and repoint inbound links. Provisioning behavior sourced from the managed-deepagents-sdkexamples/slackREADME and connector examples.Commit 5 — channels overview fold. Add a "Provider events and messaging" section to
connectors/index.mdxand repoint "Choose the right integration" at the Slack/GitHub connectors. Delete the channels overview page and the now-emptychannels/directory, remove the Channels nav group, and add redirects from/managed-deep-agents-channels(and/index) to/connectors. Repoint remaining inbound links, and reconcile stale channels prose indeployandhow-it-works(/channels/{name}/events→/connectors/{name}/events).Commit 6 — CLI reconciliation. Rename the deploy workspace flag/env to
--workspace-id/LANGSMITH_WORKSPACE_ID(LANGSMITH_TENANT_ID/--tenant-idare removed in dev84); documentmda init --scope(user,shared-conversations,organization,agent,none); rewrite the Connectors section (namedconnectorexport, add Integrations and Slack, notePOST /connectors/{name}/eventsand managed Slack provisioning); remove the Channels section; and update the project-layout snippet to foldchannels/*intoconnectors/.Commit 7 —
mda connect. Document the newmda connectcommand (dev84), which scaffolds a connector and completes its workspace OAuth from the terminal. Add a "Connect integrations" section to the CLI reference (the--listcatalog with theoauth/secret/none/deployAUTH types, the connect-by-name scaffold + browser OAuth flow, and the--list/--check/--revoke/--json/--yesflags) plus a command-overview row; add a "Connect from the CLI" subsection to the integrations page; and mention it on the connectors overview. Slack stays deploy-owned. Verified against the managed-deepagents-sdkcrates/mda/src/connect.Drafted with AI agent (dcode) assistance.