Skip to main content
LangSmith supports deploying agents from monorepo setups where your agent code may depend on shared packages located elsewhere in the repository. This guide shows how to structure your monorepo and configure your langgraph.json file to work with shared dependencies.

​
Repository Structure

For complete working examples, see: 
my-monorepo/
├── shared-utils/           # Shared Python package
│   ├── __init__.py
│   ├── common.py
│   └── pyproject.toml      # Or setup.py
├── agents/
│   └── customer-support/   # Agent directory
│       ├── agent/
│       │   ├── __init__.py
│       │   └── graph.py
│       ├── langgraph.json  # Config file in agent directory
│       ├── .env
│       └── pyproject.toml  # Agent dependencies
└── other-service/
    └── ...

​
LangGraph.json configuration

Place the langgraph.json file in your agent’s directory (not in the monorepo root). Ensure the file follows the required structure: 
{
  "dependencies": [
    ".",                    # Current agent package
    "../../shared-utils"    # Relative path to shared package
  ],
  "graphs": {
    "customer_support": "./agent/graph.py:graph"
  },
  "env": ".env"
}
The Python implementation automatically handles packages in parent directories by:
  • Detecting relative paths that start with ".".
  • Adding parent directories to the Docker build context as needed.
  • Supporting both real packages (with pyproject.toml/setup.py) and simple Python modules.
For JavaScript monorepos:
  • Shared workspace dependencies are resolved automatically by your package manager.
  • Your package.json should reference shared packages using workspace syntax.
Example package.json in the agent directory: 
{
  "name": "customer-support-agent",
  "dependencies": {
    "@company/shared-utils": "workspace:*",
    "@langchain/langgraph": "^0.2.0"
  }
}

​
Building the application

Run langgraph build: 
cd agents/customer-support
langgraph build -t my-customer-support-agent
The Python build process:
  1. Automatically detects relative dependency paths.
  2. Copies shared packages into the Docker build context.
  3. Installs all dependencies in the correct order.
  4. No special flags or commands required.
The JavaScript build process:
  1. Uses the directory you called langgraph build from (the monorepo root in this case) as the build context.
  2. Automatically detects your package manager (yarn, npm, pnpm, bun)
  3. Runs the appropriate install command.
    • If you have one or both of a custom build/install command it will run from the directory you called langgraph build from.
    • Otherwise, it will run from the directory where the langgraph.json file is located.
  4. Optionally runs a custom build command from the directory where the langgraph.json file is located (only if you pass the --build-command flag).

​
Tips and Best Practices

  1. Keep agent configs in agent directories: Place langgraph.json files in the specific agent directories, not at the monorepo root. This allows you to support multiple agents in the same monorepo, without having to deploy them all in the same LangGraph platform deployment.
  2. Use relative paths for Python: For Python monorepos, use relative paths like "../../shared-package" in the dependencies array.
  3. Leverage workspace features for JS: For JavaScript/TypeScript, use your package manager’s workspace features to manage dependencies between packages.
  4. Test locally first: Always test your build locally before deploying to ensure all dependencies are correctly resolved.
  5. Environment variables: Keep environment files (.env) in your agent directories for environment-specific configuration.
Edit the source of this page on GitHub
⌘I