Skip to main content
Agent Builder v2 is in open beta. Features and limitations described here are subject to change.
This guide shows you how to deploy your first agent with Agent Builder v2. After completing these steps, you can create an agent in AI Studio, deploy your code from your IDE or the UI, test it in a development environment, and promote it to production.

​
Prepare your environment

Before you begin, make sure you have:
  • AI Studio access with Agent Builder v2 enabled for your organization. Your Writer contact can confirm this.
  • An IDE: Cursor (recommended for one-click MCP setup), VS Code, or any MCP-compatible IDE.
  • Docker installed locally for building and testing your application.
  • Application code with a Dockerfile that listens on port 8000 by default, or any other port except 8001 (which is reserved). The port is configurable per environment.

​
Create an agent in AI Studio

Start by creating an Agent Builder v2 agent in AI Studio.
  1. Log in to AI Studio.
  2. Go to the Agents tab.
  3. Select Build an agent.
  4. Select Agent Builder v2 from the template options.
AI Studio generates an agent with a unique ID and a development environment.

​
Configure the MCP server in your IDE

After you create your agent, a Getting started modal appears with MCP configuration options. Connecting the MCP server gives your IDE access to tools for listing environments, deploying code, and managing environment variables. Cursor (one-click setup)
  • Select the deep link button in the modal. Cursor opens and configures the Writer MCP server automatically.
VS Code or other IDEs (manual JSON)
  • Select Copy JSON in the modal to copy the MCP configuration.
  • Open your IDE’s MCP settings and paste the configuration.
The MCP configuration looks like this:
OAuth tokens refresh automatically, so you don’t need to manage token expiration manually.

​
Prepare your application

Your application needs a Dockerfile. Here is an example for a Next.js application:
Your application must listen on a port other than 8001 (which is reserved). The default is 8000; if you use a different port, update it in Configure your deployment for that environment. Package your code as a .tar.gz tarball. For a Node.js application:
For a Python or FastAPI application:

​
Upload and deploy

You can deploy through the AI Studio UI or through MCP from your IDE. Deploy through the AI Studio UI
  1. Go to your agent’s Deploy tab.
  2. Select the Development environment.
  3. Select Import new snapshot.
  4. Drag and drop your .tar.gz file, or select it to browse.
  5. Select Save.
  6. Wait for the build to complete. The status changes to “In development”.
Deploy through MCP from your IDE
  1. Open your IDE with the MCP server configured.
  2. Ask your AI coding agent to deploy the agent to development. The MCP server packages your code and uploads it automatically.
  3. You can also ask it to list environments, show revision history, or report deployment status.

​
Set environment variables

Environment variables are injected into your container at runtime and are encrypted at rest.
  1. In AI Studio, select your Development environment.
  2. Go to the Environment variables tab.
  3. Select Add environment variable.
  4. Enter the variable name and value, for example WRITER_API_KEY or DATABASE_URL.
  5. Save your changes.
Development and production environments have separate environment variables. When you promote to production, set production-specific values separately.

​
Test in development

After your build completes, your application is accessible at the development URL shown in the environment detail panel.
  • The first load can take 2-5 seconds because of container cold start.
  • Subsequent requests while the container is warm are fast.
  • You can view build logs and deployment status in the version history tab.
To iterate on your code:
  1. Make changes locally.
  2. Rebuild your tarball: tar -czvf myapp.tar.gz ..
  3. Upload a new snapshot through the UI or MCP.
  4. Each upload creates a new version in version history.
  5. Roll back to any previous version if needed.

​
Promote to production

When you’re satisfied with your development deployment, promote it to production.
  1. Open the Development environment detail panel.
  2. Go to the Access tab.
  3. Select Promote to production.
  4. Select who can access the production agent:
    • Only you for private access.
    • Specific teams to select teams from the dropdown.
    • All teams to make it available to everyone in your organization.
  5. Select Promote.
Agent Builder v2 creates a separate production environment with its own URL, environment variables, and version history. After you promote, the agent also appears in the Agents tab in Writer App for you and anyone you shared it with.

​
Find your agent in Writer App

After you promote an agent to production, it appears in the Agents tab in Writer App. That list includes agents you own and agents that teammates have shared with you. From the Agents tab you can:
  • Open a production agent to run it.
  • See the Version for each agent, which matches the version of that agent’s production environment in AI Studio.
  • See Views, which shows how many people have viewed the agent in the past 30 days.
  • Search and filter by All, Favorites, Tags, or Owned by.

​
Organize agents with tags

As your library of Agent Builder v2 agents grows, tags help you keep everything organized and find what you need. Tags are personal to you, so you can build a system that matches how you work, whether that’s by use case, project, or any other category that’s useful to you.
  1. Go to the Agents tab in Writer App.
  2. Hover over the agent you want to tag and select Add tag.
  3. Create a new tag or choose an existing one to apply it.
  4. Select Manage tags in the Tags filter to rename, delete, or recolor tags.
You can apply multiple tags to a single agent if it fits more than one category. Tags only apply to your view of agents.

​
Use bulk actions

You can manage multiple agents at once from the Agents tab. Use the checkboxes next to your agents to open the bulk actions menu, then select Add to favorites or Tag.
Use tags to create a personal organizational system that grows with your agent library. Grouping by workflow type, project, or how often you use an agent can help you find the right one faster.

​
Configure your deployment

Each environment has deployment settings that control how your container runs. The defaults work for most agents; adjust them when you need to tune resources, cold-start behavior, or the port your app listens on. The configuration applies to the environment’s most recent version.
  1. Open the environment detail panel and select Configure deployment.
  2. Adjust the settings as needed:
  1. Select Save. The settings apply to the latest version in that environment.
Development and production each have their own deployment configuration, so you can tune them independently.

​
Change the deployment URL

Each environment has a deployment URL you can edit from the environment detail panel. Changing it retires the current URL immediately, so update any bookmarks, API callers, or integrations that still use it.
  1. Open the Agent Builder v2 agent in AI Studio.
  2. Select the environment whose URL you want to change.
  3. Select the deployment URL at the top of the environment detail panel.
  4. Review the confirmation. The current URL stops working, and existing links and integrations break until you update them.
  5. Optionally select Don’t warn me again for this environment if you don’t want this confirmation the next time you edit this environment’s URL.
  6. Select Yes, edit URL, then enter the new URL and save.

​
Call your agent via API

In addition to the UI-driven experience in AI Studio, Agent Builder v2 supports headless usage. If your application exposes HTTP endpoints, you can call them programmatically from any external service, script, or frontend using an API key. This is useful when you want to:
  • Embed your agent into another application or product surface.
  • Call your agent from a backend service, scheduled job, or CI pipeline.
  • Integrate your agent with existing tooling outside AI Studio.

​
Generate an API key

Each environment has its own API keys, so development and production keys are managed separately. An environment API key authenticates machine calls to that environment’s /_api and /api endpoints without a user session.
  1. Open your agent in AI Studio and select the environment you want to call, such as Development or Production.
  2. Select the three vertical dots in the environment and select Generate API key.
  3. Select Generate key.
  4. Copy the key when it’s displayed. This is the only time the full key is shown, so store it securely in a secrets manager.

​
Make a request to your agent

Use the environment’s deployment URL as the base URL and pass the API key as a bearer token in the Authorization header. You can call any endpoint your application exposes.
The request and response shape is whatever your application defines. Agent Builder v2 doesn’t enforce a specific schema, so any endpoint inside your container is callable as long as the API key is valid for that environment.

​
Manage keys

Each environment has one API key at a time. You can:
  • Create a key in the AI Studio UI when you first need API access for an environment.
  • Regenerate a key in the AI Studio UI when you need to rotate it. The old key stops working immediately and a new one is issued.

​
Next steps