Skip to content

AGENTS.md

Latest commit

 

History

History
375 lines (269 loc) · 20.9 KB

AGENTS.md

File metadata and controls

375 lines (269 loc) · 20.9 KB

Keep in sync: AGENTS.md and CLAUDE.md contain identical guidelines. If you update one, update the other.

LangChain Documentation Guidelines

Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under src/, not Mintlify build/ output.

Critical rules

  1. Always ask for clarification rather than making assumptions
  2. Never fabricate examples, JSON snippets, policy details, or use case descriptions — use only content from the user or existing source files
  3. Never use markdown in frontmatter description — breaks SEO
  4. Never edit build/ — Mintlify build output (regenerate with make build or make dev)
  5. Always update src/docs.json when adding new pages
  6. Use Tabler icons only — not FontAwesome
  7. Test code examples before including them

Quick reference

What Where/How
LangSmith docs src/langsmith/
Open source docs src/oss/ (LangChain, LangGraph, Deep Agents)
Python integrations src/oss/python/integrations/
JS integrations src/oss/javascript/integrations/
Reusable snippets src/snippets/
Images src/images/
Provider icons src/images/providers/
Navigation config src/docs.json
Build system pipeline/
Icon library Tabler — https://tabler.io/icons
Mintlify components https://mintlify.com/docs/components
API reference site reference.langchain.com — built outside this repo; report reference docs issues
Mintlify MCP server npx add-mcp https://www.mintlify.com/docs/mcp

Project structure

This project uses Mintlify for documentation. Key files: src/docs.json (navigation + site config), MDX files with YAML frontmatter for page metadata. When making multi-file docs changes, always update src/docs.json navigation and any redirect mappings. Custom CSS lives in src/style.css.

docs/
├── src/                        # All manually authored content
│   ├── docs.json               # Mintlify config + navigation
│   ├── index.mdx               # Home page
│   ├── style.css               # Custom CSS
│   ├── langsmith/              # LangSmith product docs
│   ├── oss/                    # Open source docs
│   │   ├── langchain/          #   LangChain framework
│   │   ├── langgraph/          #   LangGraph framework
│   │   ├── deepagents/         #   Deep Agents
│   │   ├── python/             #   Python-specific (integrations, migrations, releases)
│   │   ├── javascript/         #   TypeScript-specific (integrations, migrations, releases)
│   │   ├── integrations/       #   Shared integration content
│   │   ├── concepts/           #   Conceptual overviews
│   │   ├── contributing/       #   Contribution guides
│   │   └── reference/          #   Reference tab entry pages (link to reference.langchain.com)
│   ├── snippets/               # Reusable MDX snippets
│   │   ├── langsmith/          #   LangSmith snippets
│   │   ├── oss/                #   OSS snippets
│   │   └── code-samples/       #   Embedded code samples
│   ├── images/                 # Documentation images
│   │   ├── brand/              #   Logos, favicons
│   │   └── providers/          #   Provider icons (dark/ and light/ variants)
│   └── fonts/                  # TWK Lausanne font files
├── pipeline/                   # Python build system & preprocessors
├── build/                      # Build output — do not edit
├── scripts/                    # Helper utilities
└── tests/                      # Pipeline tests

Navigation map

Navigation is defined in src/docs.json. The site has 4 products (Home, LangSmith, LangSmith Fleet, Open source). When adding pages, find the correct product/tab/group below, then update the matching section in docs.json.

Home

Single page (src/index.mdx). No tabs.

LangSmith (src/langsmith/)

7 tabs, all files in src/langsmith/:

Tab Groups
Get started Account administration (Workspace setup, Users & access control, Billing & usage), Tools, Additional resources
Observability Tracing setup, Configuration & troubleshooting, Viewing & managing traces, Automations, Feedback & evaluation, Monitoring & alerting, Data type reference
Evaluation Datasets, Set up evaluations, Analyze experiment results, Annotation & human feedback, Common data types
Prompt engineering Create and update prompts, Tutorials
Agent deployment Agent server, Core capabilities, Develop agents, Deployment guides, Studio, Auth & access control, Server customization
Platform setup Overview, Hybrid, Self-hosted (by cloud provider, Setup guides, Enable features, Configuration, External services, Auth, Observability, Scripts)
Reference LangSmith Deployment (Agent Server API, Control Plane API), Releases

All LangSmith files are flat in src/langsmith/ (no per-tab subdirectories except fleet/ and images/).

LangSmith Fleet (src/langsmith/fleet/)

Flat groups (no tabs):

  • Get started
  • Configure
  • Tools and automation
  • Advanced
  • Additional resources

Open source (src/oss/)

2 language dropdowns (Python, TypeScript), each with 7 tabs sharing the same names. Groups listed below are for the Python dropdown; TypeScript groups differ in some tabs (noted with *).

Tab Directory Groups
Deep Agents src/oss/deepagents/ Get started, Deployment, Core capabilities, Frontend, Protocols, Code
LangChain src/oss/langchain/ Get started, Core components, Middleware, Frontend, Advanced usage, Agent development, Production
LangGraph src/oss/langgraph/ Get started, Capabilities, Production, Frontend, LangGraph APIs
Integrations* src/oss/python/integrations/ or src/oss/javascript/integrations/ Popular Providers, Integrations by component (TS: "General integrations, RAG integrations")
Learn* src/oss/ (various) Tutorials, Conceptual overviews, Additional resources (TS adds: "LangChain Academy")
Reference src/oss/reference/ Reference, Errors, Releases, Policies — short entry pages linking to reference.langchain.com
Contribute src/oss/contributing/ Contribution guides, integration authoring

Local development

See Contributing to documentation for setup instructions.

Frontmatter

Every MDX file requires:

---
title: Clear, concise page title
description: SEO summary — no markdown allowed (no links, backticks, formatting)
---

Integration page descriptions: "Integrate with the ClassName type using LangChain Python."

  • Example: "Integrate with the ChatOpenAI chat model using LangChain Python."

Syntax

Language-specific content

Use :::python or :::js fences for language-specific content. Pages with these fences generate separate Python and JavaScript versions.

:::python
Python-only content here
:::

Code highlighting

highlighted = True  # [!code highlight]
added = True        # [!code ++]
removed = True      # [!code --]

API reference links

Use @[ClassName] to auto-link to API docs. Defined in pipeline/preprocessors/link_map.py.

Use for: First mention of SDK classes/methods (@[ChatOpenAI], @[StateGraph], @[create_agent])

Don't use for: Repeated mentions, general concepts, or when a descriptive link is clearer

Assets

Images: Store in src/images/. Use descriptive filenames and alt text.

Icons: Use Tabler names only (icon="home", icon="brand-github"). For missing icons, use SVG path: icon="/images/providers/name.svg"

Common Tabler names: home (not house), tool (not wrench), player-play (not play), bulb (not lightbulb), alert-triangle (not exclamation-triangle)

Components

Component Use for
<Tabs> / <Tab> Python/JS examples
<Steps> / <Step> Numbered instructions
<Accordion> Collapsible content
<CodeGroup> Tabbed code blocks
<Card> / <CardGroup> Navigation/overview links only (not for highlighting points)
<Note>, <Tip>, <Warning>, <Info> Callouts

Version-added admonitions

When documenting new features, APIs, or behavior that requires a minimum package or CLI version, add a version-added admonition near the first mention of the feature. Use a <Note> callout with a concise requirement, for example: Feature name requires \package>=x.y.z`.`

For language-specific requirements, wrap the note in the relevant :::python or :::js fence. Include separate notes when Python and TypeScript packages have different minimum versions.

Mermaid diagram styling

Use these classDef colors (from LangChain brand palette) for all mermaid diagrams. See .github/brand-guidelines.md for the full brand color reference.

Role classDef value
process (blue) fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
trigger (green) fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
decision (purple) fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
output (plum) fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
alert (peach) fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
neutral (muted blue) fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68

When using %%{init}%% theme variables, use: lineColor:'#40668D', primaryColor:'#E5F4FF', primaryTextColor:'#030710', primaryBorderColor:'#006DDD'.

Do not use Tailwind default colors, Material Design colors, or other off-brand palettes in mermaid diagrams.

Style guide

Follow Google Developer Documentation Style Guide.

Do:

  • Match existing conventions in the file you are editing — do not restructure, combine, or split pages unless explicitly asked
  • Reference existing pages for style patterns when creating new content
  • Be concise — cut filler words and wordy phrases ("to" not "in order to", "because" not "due to the fact that", "can" not "has the ability to")
  • Second-person imperative present tense ("Run the following code…")
  • Active voice ("The function returns a list" not "A list is returned by the function")
  • Sentence-case headings starting with active verb, not gerund ("Add a tool" not "Adding a tool")
  • American English spelling
  • Oxford commas in lists ("traces, datasets, and experiments")
  • Descriptive link text ("View the tracing docs" not "click this link")
  • Add cross-links where applicable
  • Use @[ClassName] link map for API references
  • Use :::python/:::js fencing on OSS docs
  • Language tags on all code blocks (use actual language, not output)
  • Sort imports in all code snippets (stdlib, third-party, local)
  • Use .content_blocks instead of .content when accessing message content in LangChain code snippets
  • Test code examples and links before publishing

Don't:

  • Skip frontmatter
  • Use absolute URLs for internal links
  • Use markdown in description fields
  • Use /python/ or /javascript/ in links (resolved by build pipeline)
  • Use model aliases — use full identifiers (e.g., claude-sonnet-4-6)
  • Use FontAwesome icon names
  • Use nested double quotes in component attributes — use default="['a', 'b']" not default='["a", "b"]'
  • Use contractions ("do not" not "don't", "cannot" not "can't", "it is" not "it's")
  • Use first person ("we", "I", "our", "let's") — write in second person or use the product name as subject
  • Use future tense ("The function returns X" not "The function will return X")
  • Use weasel words or filler (avoid "simply", "easily", "just", "very", "basically", "obviously")
  • Use H5 or H6 headings
  • Start headings with articles ("Add a tool" not "The tool setup guide")
  • Use em dashes — prefer commas, colons, or separate sentences instead. Only use an em dash when no alternative reads naturally
  • Add spaces around em dashes — write word—word not word — word (make lint_prose enforces this)
  • Use excessive bold/italics in body text
  • Start bulleted list items with a lowercase letter — always capitalize the first word
  • Include "key features" lists
  • Use horizontal lines (---) to separate sections — use headings instead
  • Apply bold to UI element names unless existing docs already do so
  • Misspell product names — use "prebuilt" (not "pre-built"), "Deep Agents" (not "DeepAgents"), "PyPI" (not "PyPi"), "URL" (not "url")
  • Skip make lint_prose — always run it on changed files before committing and fix all violations

Structure conventions

Match these patterns, drawn from established pages, when authoring new content:

  • Open with definition, then benefit, then task — start a section (and the page) with a one-sentence statement of what the feature is or does, follow with a sentence on what it enables for the reader, then give the procedure or detail. When a page has a sibling variant (for example, a paid or self-hosted version), link it in the opening lines.
  • Introduce procedures with a colon lead-in — precede steps with a phrase such as "To add a channel:", then a numbered list (or the <Steps> component) of imperative steps. State a step's result as a follow-on line when it matters ("The Add User modal displays."). Flag optional steps inline with "(Optional)". For long, multi-stage tasks, use ### Step N. <verb> headings.
  • Use bold-led definition lists for options — for parameters, permissions, secrets, or enumerated types, write - **Term**: Explanation. and end each explanation with a period.
  • Link on first mention, and point forward at section ends — link a feature, class, or term on first mention only, not on repeats. Use the pointer phrasing "For more information, see Page". Close substantial pages with a ## See also list of related links.
  • State requirements and constraints up front — put permission, plan tier, or preview requirements before the steps they govern ("Adding MCP servers requires admin permissions."). Write hard constraints as plain facts ("Once an agent identity is set, it cannot be changed.").

Model references

Always use the latest generally available (GA) models when referencing LLMs in docstrings and illustrative code snippets. Avoid preview or beta identifiers unless the model has no GA equivalent. Outdated model names signal stale code and confuse users.

Before writing or updating model references, verify current model IDs against the provider's official docs. Do not rely on memorized or cached model names — they go stale quickly.

Release stage names

LangSmith ships features through three release stages: alpha, beta, and generally available (GA). See Release stages for what each stage means.

These are common nouns, not proper nouns. Write them lowercase in prose, including parenthetical and inline status markers:

  • Lowercase mid-sentence and in markers: "available in beta", "is in beta", "(beta)", "the feature is in alpha".
  • Capitalize only where normal sentence case requires it: the first word of a sentence or heading ("Beta is optional.", "## Beta").
  • Keep the literal product UI label capitalized when quoting it as a tag: the Beta tag, frontmatter tag: "Beta". The same applies to a stage name standing alone as a table cell's only label.
  • Spell out "generally available" on first use, then use "GA". GA is always uppercase.
  • Do not change code identifiers, package version identifiers (1.0.0b1), or literal CLI output that contains "Beta".

Adding pages

  1. Create MDX file with required frontmatter in the correct directory (see navigation map above)
  2. Update src/docs.json to add the page to the correct product → tab → group
  3. For new groups, include an index page: "pages": ["group/index", "group/page"]

Common workflows

Add a new LangSmith doc:

  1. Create src/langsmith/<name>.mdx with frontmatter
  2. Find the correct tab and group in src/docs.json under navigation.products[1] (LangSmith)
  3. Add the page path (e.g., "langsmith/<name>") to that group's pages array

Add a new integration page (Python):

  1. Create src/oss/python/integrations/<component>/<provider>.mdx
  2. Add the page to the component's index page (src/oss/python/integrations/<component>/index.mdx); only edit src/docs.json when creating a brand-new component group
  3. Use description format: "Integrate with the ClassName type using LangChain Python."
  4. If the provider has an overview page at src/oss/python/integrations/providers/<provider>.mdx, add or update a section there linking to the new page (/oss/integrations/<component>/<provider>)

Add a new integration page (TypeScript):

  1. Create src/oss/javascript/integrations/<component>/<provider>.mdx
  2. Add the page to the component's index page (src/oss/javascript/integrations/<component>/index.mdx); only edit src/docs.json when creating a brand-new component group
  3. If the provider has an overview page at src/oss/javascript/integrations/providers/<provider>.mdx, add or update a section there linking to the new page (/oss/integrations/<component>/<provider>)

Add a reusable snippet:

  1. Create src/snippets/<product>/<name>.mdx
  2. Reference with <Snippet file="<product>/<name>.mdx" />

Debugging

When investigating a bug or unexpected behavior, always start by reading the relevant code and logs before forming a hypothesis. Do not assume something is working or ask the user to confirm — verify it yourself first.

CI broken-links failures

make broken-links runs mint broken-links then filters known false positives (OpenAPI-generated pages: /langsmith/agent-server-api/, /api-reference/, ../langchain/agents). Output format:

found N broken links in M files

some-file.mdx                    ← file header (always printed)
 ⎿  /path/to/broken-target       ← indented = actual broken link

another-file.mdx                 ← no indented lines = all its links were filtered out (false positive)

Shortcut: Skip straight to ⎿ lines — those are the only real failures. File headers without ⎿ lines beneath them are OpenAPI pages that exist at deploy time but not locally.

Common cause: Page renamed/deleted but link and/or src/docs.json nav entry still references old name. Fix both the link in the MDX file AND the corresponding entry in docs.json.

To run locally: make broken-links

Helper scripts

Refresh Deep Agents eval matrix

The model-by-eval-category table on /oss/python/deepagents/models is generated by scripts/refresh_deepagents_category_matrix.py. The script pulls category_scores from the latest successful Evals - GHA runs in langchain-ai/deepagents and writes the table to src/snippets/deepagents-eval-category-matrix.mdx (imported by src/oss/deepagents/models.mdx). Run it whenever new eval results land and the published table is out of date.

Setup and run:

export GITHUB_TOKEN="$(gh auth token)"  # needs Actions: Read on langchain-ai/deepagents; SSO-authorize for langchain-ai
uv run python scripts/refresh_deepagents_category_matrix.py --write

Notes:

  • For the latest (model, category) value per cell, the script walks runs newest-first and keeps the first hit. Models with fewer than four of the six fixed categories filled are dropped (MIN_FILLED_CATEGORIES).
  • Only models explicitly listed in INCLUDED_MODELS (in the script) appear in the table. To surface a new model, add its provider:model key there.
  • The fixed columns are defined by FIXED_CATEGORY_COLUMNS in the script (unit_test is intentionally excluded).
  • Without --write, the script prints the table to stdout for inspection.
  • After regenerating, commit only src/snippets/deepagents-eval-category-matrix.mdx. Do not edit that snippet by hand.

Pre-commit linting

Always run make lint_prose (Vale) before handing off or committing doc changes. CI blocks on it. Common offenders: em-dashes with surrounding spaces (— → —, enforced by LangChain.DashesSpaces), terminology, style.

Scope to changed files for speed: make lint_prose FILES="src/path/to/file.mdx" (or pass space-separated paths). Run with no FILES arg to lint all of src/.

Also run make broken-links when adding or renaming links, pages, or nav entries.

Changelog / Release notes

When extracting data from PRs or changelogs, use the "Release Note:" section in PR bodies, not PR titles. Always verify the data source format before processing.

Pull requests

  • Explain the "why" of changes
  • Highlight areas needing careful review
  • Disclose AI agent involvement in description