Feature Request: Simplified API for storing tool results in agent filesystem

[Abdurihim]

Problem

When using custom tools with createDeepAgent, I need to manually store tool results to the agent's filesystem. The current approach requires understanding several internal concepts:

1. Extracting StateAndStore from the tool's config parameter
2. Creating a StateBackend instance
3. Handling the WriteResult.filesUpdate field
4. Returning a Command object to update LangGraph state

Current Implementation (verbose)

import { getCurrentTaskInput, Command } from "@langchain/langgraph";
import { ToolMessage } from "langchain";
import { type StateAndStore, StateBackend } from "deepagents";

tool(
  async (args, config) => {
    const result = await myExternalTool.handler(args);
    
    // Manual state extraction
    const stateAndStore: StateAndStore = {
      state: getCurrentTaskInput(config),
      store: (config as any).store,
    };
    
    // Manual backend creation
    const backend = new StateBackend(stateAndStore);
    
    // Store result
    const filePath = `/logs/${args.logid}.json`;
    const writeResult = await backend.write(filePath, JSON.stringify(result));
    
    // Handle filesUpdate manually
    if (writeResult.filesUpdate) {
      const message = new ToolMessage({
        content: `Saved to ${filePath}`,
        tool_call_id: config.toolCall?.id as string,
        name: "my_tool",
      });
      
      return new Command({
        update: { files: writeResult.filesUpdate, messages: [message] },
      });
    }
    
    return result;
  },
  { name: "my_tool", description: "...", schema: z.object({...}) }
)

Questions

1. Is this the intended pattern? The middleware handles this internally, but for custom tools that need to store results, is there a simpler API?

2. Why must we use Command? I understand LangGraph state is immutable, but could deepagents provide a helper that abstracts this?

3. Potential simplified API? Would something like this be feasible?

import { toolWithFilesystem } from "deepagents";

// Option A: Helper wrapper
const myTool = toolWithFilesystem(
  async (args, { backend }) => {
    const result = await myExternalTool.handler(args);
    await backend.write(`/logs/${args.id}.json`, result);
    return result;
  },
  { name: "my_tool", ... }
);

// Option B: Utility function
import { saveToFilesystem } from "deepagents";

tool(
  async (args, config) => {
    const result = await myExternalTool.handler(args);
    return saveToFilesystem(config, `/logs/${args.id}.json`, result);
  },
  { name: "my_tool", ... }
);

Use Case

I'm building an AI-SRE agent that queries external log and trace APIs. I want to automatically store query results in the agent's filesystem so they can be referenced later in the conversation, without the agent needing to explicitly call write_file.

Environment

• deepagents version: latest
• langchain version: latest
• Node.js version: 20+

Thank you for the great library! Looking forward to your guidance.