feat(sdk): add `artifacts_root` to `CompositeBackend` and middleware by nick-hollon-lc · Pull Request #2490 · langchain-ai/deepagents

Nick Hollon (nick-hollon-lc) · 2026-04-06T20:58:57Z

Add an optional artifacts_root parameter to CompositeBackend that propagates through FilesystemMiddleware and SummarizationMiddleware via create_deep_agent. This parameterizes the paths used for large tool result eviction (/large_tool_results/) and conversation history offloading (/conversation_history/), allowing callers to control where internal artifacts are written. Defaults to "/" for backwards compatibility.

…eware Add an optional `artifacts_root` parameter to `CompositeBackend` that propagates through `FilesystemMiddleware` and `SummarizationMiddleware` via `create_deep_agent`. This parameterizes the paths used for large tool result eviction (`/large_tool_results/`) and conversation history offloading (`/conversation_history/`), allowing callers to control where internal artifacts are written. Defaults to `"/"` for backwards compatibility.

ccurme (ccurme) · 2026-04-06T21:02:30Z

-When a tool result is too large, it may be offloaded into the filesystem instead of being returned inline. In those cases, use `read_file` to inspect the saved result in chunks, or use `grep` within `/large_tool_results/` if you need to search across offloaded tool results and do not know the exact file path. Offloaded tool results are stored under `/large_tool_results/<tool_call_id>`."""
+When a tool result is too large, it may be offloaded into the filesystem instead of being returned inline. In those cases, use `read_file` to inspect the saved result in chunks, or use `grep` within `{large_tool_results_prefix}/` if you need to search across offloaded tool results and do not know the exact file path. Offloaded tool results are stored under `{large_tool_results_prefix}/<tool_call_id>`."""
+
+FILESYSTEM_SYSTEM_PROMPT = _FILESYSTEM_SYSTEM_PROMPT_TEMPLATE.format(large_tool_results_prefix="/large_tool_results")


is this just here for backwards-compat purposes now?

yeah exactly. not sure we still need it

should this also have info about offloading of conversation history

yes probably

ok talked with chester and we don't need this unless we can come up with an eval that would fail without it. the message for a large human message comes back with how to handle it

ccurme (ccurme) · 2026-04-06T21:15:31Z

+        tool_messages = [m for m in result["messages"] if m.type == "tool"]
+        evicted_msg = next(m for m in tool_messages if m.tool_call_id == "call_big")
+        assert "/workspace/large_tool_results/" in evicted_msg.content
+        assert mem_store.get(("filesystem",), "/workspace/large_tool_results/call_big") is not None


does backend.read work?

i will add a test

similar to my above comment, i think we should actually not interact w/ the store directly

ccurme (ccurme) · 2026-04-06T21:17:33Z

+    def test_create_deep_agent_no_composite_backend(self) -> None:
+        """create_deep_agent with a non-composite backend defaults artifacts_root to '/'."""
+        model = FakeChatModelWithHistory(messages=iter([AIMessage(content="done")]))
+        agent = create_deep_agent(model=model, backend=StateBackend())  # noqa: F841
+
+    def test_create_deep_agent_composite_backend_default_artifacts_root(self) -> None:
+        """create_deep_agent with CompositeBackend without artifacts_root defaults to '/'."""
+        model = FakeChatModelWithHistory(messages=iter([AIMessage(content="done")]))
+        backend = CompositeBackend(default=StateBackend(), routes={})
+        agent = create_deep_agent(model=model, backend=backend)  # noqa: F841


what are these tests enforcing?

ccurme (ccurme) · 2026-04-06T21:27:19Z

        default: Backend for paths that don't match any route.
        routes: Map of path prefixes to backends (e.g., {"/memories/": store_backend}).
        sorted_routes: Routes sorted by length (longest first) for correct matching.
+        artifacts_root: Root path for artifacts. Defaults to `"/"`.


may make sense to flesh this out (e.g., "Root path for artifacts, such as messages offloaded by middleware").

yeah make sense to me. i'll do a quick pass on all the doc strings

Sydney Runkle (sydney-runkle)

high level, looks good, congrats on first pr!!

my one high level comment is that we might not need the artifact root on CompositeBackend if we allow folks to customize middlewares given that each middleware that uses offloading has their own artifacts path.

Curious, what was the customer use case motivating this feature?

Sydney Runkle (sydney-runkle) · 2026-04-07T11:28:27Z

        routes: dict[str, BackendProtocol],
+        *,
+        artifacts_root: str = "/",


hah just a side note but routes vs root is tough

Sydney Runkle (sydney-runkle) · 2026-04-07T11:31:52Z

        # Deep Agents specific attributes
        self._backend = backend
        self._history_path_prefix = history_path_prefix
+        self.artifacts_root = artifacts_root


why not private?

changed this

Sydney Runkle (sydney-runkle) · 2026-04-07T11:35:57Z

+def _make_store_backend():
+    mem_store = InMemoryStore()
+    backend = StoreBackend(store=mem_store, namespace=lambda _ctx: ("filesystem",))
+    return backend, mem_store


i don't think we need the mem_store returned? we could just return the backend and then do backend.download_files?

also changed this

Sydney Runkle (sydney-runkle) · 2026-04-07T11:36:44Z

+        tool_messages = [m for m in result["messages"] if m.type == "tool"]
+        evicted_msg = next(m for m in tool_messages if m.tool_call_id == "call_big")
+        assert "/workspace/large_tool_results/" in evicted_msg.content
+        assert mem_store.get(("filesystem",), "/workspace/large_tool_results/call_big") is not None


similar to my above comment, i think we should actually not interact w/ the store directly

…te tests to not interact with store directly

Sydney Runkle (sydney-runkle) · 2026-04-07T16:45:49Z

        # Deep Agents specific attributes
        self._backend = backend
+
+        self._artifacts_root = resolve_artifacts_root(backend)


nit, this is simple enough that let's just inline

self._artifacts_root = backend.artifacts_root if isinstance(backend, CompositeBackend) else "/"

that way we don't have too much indirection
generally good idea to consolidate shared logic though

Sydney Runkle (sydney-runkle) · 2026-04-07T16:46:25Z

+        assert isinstance(result, ToolMessage)
+        assert "/workspace/large_tool_results/evict_123" in result.content
+        [resp] = backend.download_files(["/workspace/large_tool_results/evict_123"])
+        assert resp.content is not None


should we check what it has? similar for other tests

Sydney Runkle (sydney-runkle) · 2026-04-07T16:46:59Z

+        evicted_msg = next(m for m in tool_messages if m.tool_call_id == "call_big")
+        assert "/workspace/large_tool_results/" in evicted_msg.content
+        [resp] = backend.download_files(["/workspace/large_tool_results/call_big"])
+        assert resp.content is not None


same let's confirm, this is important

Sydney Runkle (sydney-runkle) · 2026-04-07T16:47:59Z

                    # Truncate when 50% of context window reached, ignoring messages in last 10% of window
                    {"trigger": ("fraction", 0.5), "keep": ("fraction", 0.1), "max_length": 2000, "truncation_text": "...(truncated)"}
            history_path_prefix: Path prefix for storing conversation history.
+                Derived from the backend's `artifacts_root` when not provided.


it still uses the backend root when provided right?

or it should?

…ssertions, and remove shared method in utils since logic is simple enough

Sydney Runkle (sydney-runkle) · 2026-04-07T17:53:28Z

+        self._artifacts_root = self.backend.artifacts_root if isinstance(self.backend, CompositeBackend) else "/"
+        _root = self._artifacts_root.rstrip("/")


last nit, any reason to actually set self._artifacts_root?

not currently

Sydney Runkle (sydney-runkle) · 2026-04-07T17:54:18Z

+        [resp] = backend.download_files(["/workspace/large_tool_results/evict_123"])
+        assert resp.error is None
+        assert resp.content is not None
+        assert b"x" * 100 in resp.content


any reason not checking just for equivalence to large_content?

no will do this

Sydney Runkle (sydney-runkle)

awesome!!

…m prompt, update tests to assert equality for downloaded files, and don't set _artifacts_root on summarization and filesystem middleware as a class variable

…ready in the instructions for too large human message

> [!CAUTION] > Merging this PR will automatically publish to **PyPI** and create a **GitHub release**. For the full release process, see [`.github/RELEASING.md`](https://github.com/langchain-ai/deepagents/blob/main/.github/RELEASING.md). --- _Everything below this line will be the GitHub release body._ --- ## [0.5.1](deepagents==0.5.0...deepagents==0.5.1) (2026-04-07) ### Features * **sdk:** `BASE_AGENT_PROMPT` tweaks ([#2541](#2541)) ([812eef1](812eef1)) * **sdk:** add `artifacts_root` to `CompositeBackend` and middleware ([#2490](#2490)) ([753ee56](753ee56)) ### Bug Fixes * **sdk:** updates for multimodal ([#2514](#2514)) ([a2edf3e](a2edf3e)) --- _Everything above this line will be the GitHub release body._ --- > [!NOTE] > A **New Contributors** section is appended to the GitHub release notes automatically at publish time (see [Release Pipeline](https://github.com/langchain-ai/deepagents/blob/main/.github/RELEASING.md#release-pipeline), step 2). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Port of langchain-ai/deepagents#2490. Adds optional artifactsRoot parameter to CompositeBackend that propagates through FilesystemMiddleware and SummarizationMiddleware, parameterizing paths for large tool result eviction and conversation history offloading. Defaults to "/" for backwards compat. Co-authored-by: Sydney Runkle <[email protected]>

…angchain-ai#2490)

github-actions Bot added deepagents Related to the `deepagents` SDK / agent harness feature New feature/enhancement or request for one internal User is a member of the `langchain-ai` GitHub organization size: M 200-499 LOC labels Apr 6, 2026

Nick Hollon (nick-hollon-lc) requested review from ccurme (ccurme), Eugene Yurtsev (eyurtsev) and Sydney Runkle (sydney-runkle) April 6, 2026 20:59

ccurme (ccurme) approved these changes Apr 6, 2026

View reviewed changes

ccurme (ccurme) reviewed Apr 6, 2026

View reviewed changes

Mason Daugherty (mdrxy) changed the title ~~feat(sdk): add artifacts_root parameter to CompositeBackend and middl…~~ feat(sdk): add artifacts_root to CompositeBackend and middleware Apr 6, 2026

address review comments

da33ad0

Sydney Runkle (sydney-runkle) reviewed Apr 7, 2026

View reviewed changes

Nick Hollon (nick-hollon-lc) added 2 commits April 7, 2026 08:54

update artifacts_root to be private and change tests to reflect. upda…

715005e

…te tests to not interact with store directly

read artifacts_root off of backend instead of passing it in as a kw arg

dde2264

Sydney Runkle (sydney-runkle) reviewed Apr 7, 2026

View reviewed changes

deprecate history path prefix on summarization middleware, fix test a…

288a83e

…ssertions, and remove shared method in utils since logic is simple enough

github-actions Bot added size: L 500-999 LOC and removed size: M 200-499 LOC labels Apr 7, 2026

Sydney Runkle (sydney-runkle) reviewed Apr 7, 2026

View reviewed changes

Sydney Runkle (sydney-runkle) approved these changes Apr 7, 2026

View reviewed changes

Nick Hollon (nick-hollon-lc) added 5 commits April 7, 2026 14:04

add section about conversation history offloading to filesystem syste…

94fb7cd

…m prompt, update tests to assert equality for downloaded files, and don't set _artifacts_root on summarization and filesystem middleware as a class variable

fix formatting and linting issues

4b5a465

undo addition of conversation history to filesystem system prompt. al…

a7d9f0a

…ready in the instructions for too large human message

warn about deprecated history path prefix and use it for now

c0609cd

fix linting/formatting

7912869

update deprecation warning to match existing patterns in repo

9315fdb

ccurme (ccurme) approved these changes Apr 7, 2026

View reviewed changes

Nick Hollon (nick-hollon-lc) enabled auto-merge (squash) April 7, 2026 20:39

Nick Hollon (nick-hollon-lc) merged commit 753ee56 into main Apr 7, 2026
33 checks passed

Nick Hollon (nick-hollon-lc) deleted the nh/add-artifacts-root branch April 7, 2026 20:44

github-actions Bot mentioned this pull request Apr 7, 2026

release(deepagents): 0.5.1 #2520

Merged

open-swe Bot mentioned this pull request Apr 8, 2026

feat: add artifactsRoot to CompositeBackend and middleware langchain-ai/deepagentsjs#440

Closed

4 tasks

github-actions Bot mentioned this pull request Apr 15, 2026

release(deepagents): 0.5.4 #2740

Closed

james8814 pushed a commit to james8814/deepagents that referenced this pull request May 1, 2026

feat(sdk): add artifacts_root to CompositeBackend and middleware (l…

9ec547a

…angchain-ai#2490)

		self._artifacts_root = self.backend.artifacts_root if isinstance(self.backend, CompositeBackend) else "/"
		_root = self._artifacts_root.rstrip("/")

Uh oh!

Conversation

Nick Hollon (nick-hollon-lc) commented Apr 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nick Hollon (nick-hollon-lc) Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sydney Runkle (sydney-runkle) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sydney Runkle (sydney-runkle) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Nick Hollon (nick-hollon-lc) Apr 6, 2026 •

edited

Loading