configuration & deployment

77 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Reserved platform variables in mda deploy

LANGSMITH_API_KEY, LANGGRAPH_HOST_API_KEY, LANGCHAIN_API_KEY, and other platform variables are reserved. They can authenticate the deploy, but they are not uploaded as user-managed deployment secrets. They are not copied into the compiled build archive.

.env file handling in mda deploy

`mda deploy` reads project .env values before shell environment variables. The .env file should contain the LANGSMITH_API_KEY for authentication and runtime secrets needed by the hosted deployment, such as model provider keys, MCP tokens, and custom tool credentials.

Non-blocking deploy with mda deploy --no-wait

Use the `--no-wait` flag with `mda deploy` to trigger the build without polling for completion. When `--no-wait` is set, schedule reconciliation is skipped for that deploy invocation because the CLI exits before the deployment reaches DEPLOYED state.

Creating production deployment with mda deploy

Use the `--deployment-type prod` flag with `mda deploy` to create a production deployment. Example: `uv run mda deploy --deployment-type prod` for Python or `npx mda deploy --deployment-type prod` for JavaScript.

Files not copied into build archive

Reserved platform variables, empty values, .env, and .env.* files are not copied into the compiled build archive by mda deploy.

Managed Deep Agent deployment process

Deploying a Managed Deep Agent compiles a code-first project into a managed LangGraph app, syncs deploy-owned context to Context Hub, uploads the compiled source, and triggers a LangSmith hosted deployment build.

Prerequisites for Managed Deep Agent deployment

Before deploying, ensure you have: a workspace with Managed Deep Agents public beta access; a LangSmith API key in .env or shell environment; the mda CLI installed from managed-deepagents; project dependencies installed (uv sync for Python, npm install for JavaScript); and model provider credentials in .env, shell environment, or LangSmith workspace secrets.

mda CLI default target region

The mda CLI targets US LangSmith Cloud by default.

mda deploy command for Python

To deploy a Managed Deep Agent in a Python project, run `uv run mda deploy` in the project directory.

mda deploy command for JavaScript

To deploy a Managed Deep Agent in a JavaScript project, run `npx mda deploy`, `pnpm exec mda deploy`, or `bunx mda deploy` depending on the package manager.

mda deploy routing of local files

When `mda deploy` is run, local project files are routed as follows: instructions.md and skills/** are routed to Context Hub deploy-owned context; .env entries are routed to deploy auth and non-reserved hosted secrets; project source files are archived to .mda/build; and schedules/** are uploaded as LangSmith cron jobs after deployment is live.

Setting explicit deployment name with mda deploy

Use the `--name` flag with `mda deploy` to set the deployment name explicitly when the directory name is not the desired name. Example: `uv run mda deploy --name research-assistant` for Python or `npx mda deploy --name research-assistant` for JavaScript.

Model provider key requirement in mda deploy

If the configured model requires a provider key, deploy fails before upload unless that key is available from .env, the shell environment, or LangSmith workspace secrets. When the provider key is only in the shell environment, `mda deploy` forwards it as a secret for that deploy.

Non-reserved secrets forwarding in mda deploy

Non-reserved .env entries such as model provider keys, MCP tokens, and custom tool credentials are forwarded as hosted deployment secrets when `mda deploy` creates or updates the deployment.

Troubleshooting: deploy API key and workspace access

If deploy fails with 401 or 403, confirm the API key belongs to a workspace with beta access.

mda dev command for Python

mda dev compiles a project and runs the local LangGraph dev server. For Python projects, it runs: uv run --with langgraph-cli[inmem]>=0.4.30 langgraph dev. Install uv before running mda dev.

mda dev command for TypeScript

mda dev compiles a project and runs the local LangGraph dev server. For TypeScript projects, it runs: npx --yes @langchain/langgraph-cli dev.

mda dev environment staging

For local development, mda dev stages the project .env file into .mda/build/.env so LangGraph can load model provider keys and other runtime credentials.

Python troubleshooting: missing uv for mda dev

If mda dev cannot find uv, install uv so mda dev can resolve the local LangGraph dev server.

mda build command

mda build compiles a project into a managed LangGraph app without deploying it. Arguments: path (project directory, defaults to current directory); --out OUT (output directory for compiled app, defaults to <path>/.mda/build, directory is emptied before build).

Troubleshooting: missing model provider API key

If deploy reports missing model provider API key, add the provider key (such as OPENAI_API_KEY) to .env, export it in shell, or configure it as a LangSmith workspace secret.

Troubleshooting: Context Hub conflict during deploy

If deploy reports a Context Hub conflict, the Context Hub repo changed during deploy. Re-run mda deploy.

Troubleshooting: build size exceeds 200 MB

If build exceeds 200 MB, remove generated artifacts or large files from the project before deploying.

Troubleshooting: deployment build or deploy failure

If deployment reaches BUILD_FAILED or DEPLOY_FAILED state, open the printed deployment URL in LangSmith and inspect the revision logs.

Troubleshooting: project root not a directory

If 'project root ... is not a directory' error occurs, pass a directory path to mda dev or mda deploy.

Troubleshooting: No LangSmith API key found

If No LangSmith API key found error occurs, set LANGSMITH_API_KEY or add it to the project .env.

mda CLI tool installation and package

The mda CLI is included with the managed-deepagents Python package (PyPI) or the managed-deepagents npm package (npm). It compiles and deploys code-first Managed Deep Agents.

mda deploy API key lookup order

The mda deploy command reads API keys in this order: 1. LANGGRAPH_HOST_API_KEY; 2. LANGSMITH_API_KEY; 3. LANGCHAIN_API_KEY. The CLI reads values from the project .env file first, then from the process environment. If no key is found in an interactive terminal, mda deploy prompts for a LangSmith API key and saves it to the project .env file.

Deploy with organization-scoped API key

To deploy with an organization-scoped key, set LANGSMITH_WORKSPACE_ID in .env or pass --workspace-id to mda deploy.

.env reserved and non-reserved variables

mda deploy forwards non-reserved .env entries such as OPENAI_API_KEY, MCP tokens, and custom tool credentials as hosted deployment secrets. Reserved platform variables (LANGSMITH_API_KEY, LANGGRAPH_HOST_API_KEY, LANGCHAIN_API_KEY, LANGSMITH_WORKSPACE_ID) are used for CLI authentication and deploy routing but are not uploaded as user-managed deployment secrets.

mda deploy process steps

mda deploy runs: 1. Validate project directory and load agent entry file; 2. Resolve LangSmith API key and optional workspace ID; 3. Collect non-reserved .env values as hosted deployment secrets; 4. Verify model provider API key availability; 5. Sync deploy-owned context to Context Hub; 6. Compile project into .mda/build and extract schedules/channels; 7. Create or find LangSmith hosted deployment by name; 8. Archive build, upload it, trigger remote build; 9. Poll revision until DEPLOYED unless --no-wait is set; 10. Reconcile managed LangSmith cron jobs unless --no-wait is set; 11. Provision declared Slack channel with optional authorization flow.

Slack channel blocks --no-wait flag

A project with a Slack channel cannot use --no-wait because Slack provisioning requires the deployed Agent Server URL.

Initialize Slack channel in existing project

Run mda channels init slack from the root of an existing managed deep agent project. The command creates a Slack channel declaration in the channels/ directory. The next mda deploy sets up resources for the agent to appear in Slack.

mda evals init command

mda evals init creates evals/harbor-job.json when missing and generates Harbor adapter and runtime settings under .mda/evals/. Run from project root. Use -i or --interactive to start a detected coding agent with the eval-engineering prompt, or copy the prompt for another agent.

mda evals compile internal command

mda evals compile is an internal command used by the Harbor job plugin. The plugin runs it when a Harbor job starts, so users do not compile eval artifacts separately.

Python mda build example

To build a Python project: uv run mda build

JavaScript mda build examples

To build a TypeScript project: npm: npx mda build; pnpm: pnpm exec mda build; bun: bunx mda build

Python mda evals init interactive example

To initialize evals with interactive handoff: uv run mda evals init -i

JavaScript mda evals init interactive examples

To initialize evals with interactive handoff: npm: npx mda evals init -i; pnpm: pnpm exec mda evals init -i; bun: bunx mda evals init -i

Python mda dev example

To develop locally: uv run mda dev

JavaScript mda dev examples

To develop locally: npm: npx mda dev; pnpm: pnpm exec mda dev; bun: bunx mda dev

Python mda deploy example

To deploy: uv run mda deploy

JavaScript mda deploy examples

To deploy: npm: npx mda deploy; pnpm: pnpm exec mda deploy; bun: bunx mda deploy

Python mda logs example

To tail Agent Server logs: uv run mda logs

JavaScript mda logs examples

To tail Agent Server logs: npm: npx mda logs; pnpm: pnpm exec mda logs; bun: bunx mda logs

Python mda delete example

To delete a deployed agent: uv run mda delete

JavaScript mda delete examples

To delete a deployed agent: npm: npx mda delete; pnpm: pnpm exec mda delete; bun: bunx mda delete

Python mda channels init example

To initialize Slack channel in existing project: uv run mda channels init slack

JavaScript mda channels init examples

To initialize Slack channel in existing project: npm: npx mda channels init slack; pnpm: pnpm exec mda channels init slack; bun: bunx mda channels init slack

Configuration through project files

Configure the system prompt, skills, memory, sandbox, identity, channels, and schedules through their project files rather than the agent definition.

Using agent after deployment

After the first deployment, the Managed Deep Agent sends a direct message in Slack. The user replies to that message to start an agent run. The final response appears in the Slack conversation.

Redeploy after Slack channel appearance changes

After changing the agent's name, description, icon, or background color in the Slack channel declaration, redeploy the agent to apply the changes in Slack.

One Slack channel per deployment

A managed deep agent deployment supports one Slack channel.

Slack channel invocation methods

A Slack channel lets people invoke a managed deep agent through app mentions, direct messages, and replies in an active Slack thread.

How Slack channel maps conversations to threads

Managed Deep Agents verifies Slack events, maps each conversation to a thread, runs the agent as the resolved caller, and posts the response back to Slack.

allow_bot_triggers parameter

The `allow_bot_triggers` parameter in Python (or `allowBotTriggers` in JavaScript) controls whether messages from other Slack bots can start agent runs. Default is `False` or `false`.

trigger_on_all_messages parameter

The `trigger_on_all_messages` parameter in Python (or `triggerOnAllMessages` in JavaScript) controls whether every new channel message can start an agent run. Default is `False` or `false`. When `False`/`false`, channel messages start runs only when they mention the agent; direct messages still start runs.

Slack channel background color parameter

The `background_color` parameter in Python (or `backgroundColor` in JavaScript) sets the background color behind the agent icon as a six-digit hexadecimal color, such as `#1d4ed8`.

Slack channel icon parameter

The `icon` parameter (or `icon` in JavaScript) specifies a path to the agent icon shown in Slack, relative to the `channels/` directory. The icon must be a 512 by 512 pixel PNG file no larger than 1 MB. If omitted, Managed Deep Agents will generate an icon automatically.

Slack channel description parameter

The `description` parameter (or `description` in JavaScript) sets a description of what the agent does. The description can contain up to 139 characters.

Give your agent this brain