official “Apply patch” docs are wrong and here is a fix

[dazzaji]

The problem

In the official “Apply patch” docs here, the Python Agents SDK example shows this usage:

from agents import Agent, ApplyPatchTool, Runner, apply_diff

class WorkspaceEditor:
    async def create_file(self, operation):
        # convert the diff to the file content
        content = apply_diff("", operation.diff, create=True)
        # write the file content to the file system
        return {"status": "completed", "output": f"Created {operation.path}"}

Our harness did exactly that initially:

new_content = apply_diff("", diff, create=True)

But in your actual environment (openai-agents==0.5.1), that failed at runtime with:

apply_diff() got an unexpected keyword argument 'create'

So the published Python example is out of sync with the current library.

What actually works

From your logs we know:

• apply_diff("", diff, create=True) → raises TypeError.
• apply_diff("", diff, "create") → successfully returns the expected file content and the subsequent create_file operation works.

We also confirmed that:

• apply_diff(current, diff) (two-argument form, no create flag) works correctly for update_file.

So the actual working pattern is:

from agents import apply_diff

# For create_file
new_content = apply_diff("", operation.diff, "create")

# For update_file
current = file_path.read_text(encoding="utf-8")
new_content = apply_diff(current, operation.diff)

How we discovered it

Step-by-step:

1. We followed the docs and used apply_diff("", diff, create=True) for create_file.

2. Your run showed:

   ERROR | PATCH[...] error applying operation: apply_diff() got an unexpected keyword argument 'create'
   

3. That told us the apply_diff signature in the installed openai-agents version does not accept a create= keyword.

4. The TS example in the same docs uses:

   const content = applyDiff("", operation.diff, "create");

   which strongly suggests the Python version likely mirrors that with a third positional argument.

5. We changed the Python call to:

   new_content = apply_diff("", diff, "create")

   and reran your tasks.

6. The next run showed:

   PATCH[...] created file hello.py with content preview:
   print("Hello from GPT-5.1")
   

   No errors, and files were created and updated correctly. That confirmed the correct signature.

So: we used the runtime error plus the TS example as evidence that the Python docs are stale.

Suggested doc fix and insertion point

Insertion point: in the “Use the apply patch tool with the Agents SDK” section under the Python example, where apply_diff is shown.

Current (incorrect) example:

from agents import Agent, ApplyPatchTool, Runner, apply_diff

class WorkspaceEditor:
    async def create_file(self, operation):
        # convert the diff to the file content
        content = apply_diff("", operation.diff, create=True)
        # write the file content to the file system
        return {"status": "completed", "output": f"Created {operation.path}"}

    async def update_file(self, operation):
        # read the file content from the file system
        current = ""
        # convert the diff to the new file content
        new_content = apply_diff(current, operation.diff)
        # write the updated file content to the file system
        return {"status": "completed", "output": f"Updated {operation.path}"}

Suggested corrected example:

from agents import Agent, ApplyPatchTool, Runner, apply_diff

class WorkspaceEditor:
    async def create_file(self, operation):
        # convert the diff to the file content
        # use "create" mode as the third positional argument
        content = apply_diff("", operation.diff, "create")
        # write the file content to the file system
        return {"status": "completed", "output": f"Created {operation.path}"}

    async def update_file(self, operation):
        # read the file content from the file system
        current = ""  # TODO: load from disk
        # convert the diff to the new file content
        new_content = apply_diff(current, operation.diff)
        # write the updated file content to the file system
        return {"status": "completed", "output": f"Updated {operation.path}"}

And ideally add a one-line clarification underneath:

In Python, apply_diff takes (current_content, diff, mode=None), where mode="create" should be used for create_file operations.

That makes the Python example consistent with the working behavior and with the TS example.

[dazzaji]

anybody home?