Build and Refine Codebases with AI

Building a Coding Agent with GPT-5.1 and the OpenAI Agents SDK

GPT-5.1 is exceptionally strong at coding, and with the new code-editing and command-execution tools available in the Responses API, it’s now easier than ever to build coding agents that can work across full codebases and iterate quickly.

In this guide, we’ll use the Agents SDK to build a coding agent that can scaffold a brand-new app from a prompt and refine it through user feedback. Our agent will be equipped with the following tools:

• apply_patch - to edit files
• shell - to run shell commands
• web_search - to pull fresh information from the web
• Context7 MCP - to access up-to-date documentation

We’ll begin by focusing on the shell and web_search tools to generate a new project with web-sourced context. Then we’ll add apply_patch so the agent can iterate on the codebase, and we’ll connect it to the Context7 MCP server so it can write code informed by the most recent docs.

Set up the agent

With the Agents SDK, defining an agent is as simple as providing instructions and a list of tools. In this example, we want to use the newest gpt-5.1 model for its state-of-the-art coding abilities.

We’ll start by enabling web_search, which gives the agent the ability to look up up-to-date information online, and shell, which lets the agent propose shell commands for tasks like scaffolding, installing dependencies, and running build steps.

The shell tool works by letting the model propose commands it believes should be executed. Your environment is responsible for actually running those commands and returning the output.

The Agents SDK automates most of this command-execution handshake for you-you only need to implement the shell executor, the environment in which those commands will run.

Define a working environment and shell executor

For simplicity, we'll run shell commands locally and isolate them in a dedicated workspace directory. This ensures the agent only interacts with files inside that folder.

Note: In production, always execute shell commands in a sandboxed environment. Arbitrary command execution is inherently risky and must be tightly controlled.

We’ll now define a small ShellExecutor class that:

• Receives a ShellCommandRequest from the agent
• Optionally asks for approval before running commands
• Runs them using asyncio.create_subprocess_shell
• Returns a ShellResult with the outputs

All commands will run with cwd=workspace_dir, so they only affect files in that subfolder.

Define the agent

Start a new project

Let’s send a prompt to our coding agent and then inspect the files it created in the workspace_dir.
In this example, we'll create a NextJS dashboard using the shadcn library.

Note: sometimes you might run into an MaxTurnsExceeded error, or the project might have a dependency error. Simply run the agent loop again. In a production environment, you would implement an external loop or user input handling to iterate if the project creation fails.

Once the agent is done creating the initial project (you should see a "=== Run complete ===" log followed by the final answer), you can check the output with the following commands:

cd coding-agent-workspace/<name_of_the_project>
npm run dev

You should see something like this:

Iterate on the project

Now that we have an initial version of the app, we can start iterating using the apply_patch tool. We also want to include calls to the OpenAI Responses API, and for that, the model should have access to the most up-to-date documentation. To make this possible, we’ll connect the agent to the Context7 MCP server, which provides up-to-date docs.

Set up the apply_patch tool for in-place edits

Note: in production you’ll typically want to run these edits in a sandboxed project workspace (e.g. ephemeral containers), and work with IDEs.

Connect to the the Context7 MCP server

Update the agent

Let's create a new agent that also uses these two additional tools, and update the instructions accordingly.
To avoid a context mismatch when applying the diffs, for this agent we'll specify not to edit files via a command.

Run the agent to edit the project

Once the agent is done updating the project (you should see a "=== Run complete ===" log followed by the final answer), you will see the updated UI, with the OpenAI Responses API call to summarize what's on the dashboard.

Note: If this step fails, you can re-run the agent loop. In a production environment, you would implement an outer loop that handles errors or wait for user input and iterate.

Wrapping up

In this cookbook guide, we built a coding agent that can scaffold a project, refine it through patches, execute commands, and stay up to date with external documentation. By combining GPT 5.1 with the Agents SDK and tools like shell, apply_patch, web_search, and the Context7 MCP, you can create agents that don’t just generate code-they actively work with codebases: running commands, applying edits, pulling in fresh context, and evolving a project end-to-end.

This workflow is a powerful blueprint for building agents that feel less like tools and more like collaborators. You can extend this pattern to integrate agents into IDEs or code sandboxes, generate new apps from scratch, work across large codebases, or even collaborate with developers in real time.