> ## Documentation Index
> Fetch the complete documentation index at: https://dev.writer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Builder v2 quickstart

> Create an agent, connect your IDE, deploy a snapshot, and promote to production with Agent Builder v2. Includes headless API access for your deployed agent.

<Note>
  Agent Builder v2 is in open beta. Features and limitations described here are subject to change.
</Note>

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](#configure-your-deployment).

## 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:

```json theme={null}
{
  "mcpServers": {
    "writer-applications": {
      "url": "https://app.writer.com/mcp/applications"
    }
  }
}
```

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:

```dockerfile theme={null}
FROM node:20-alpine AS base

# ... your build stages ...

FROM base AS runner
ENV HOSTNAME=0.0.0.0
ENV PORT=8000
EXPOSE 8000
CMD ["node", "server.js"]
```

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](#configure-your-deployment) for that environment.

Package your code as a `.tar.gz` tarball. For a Node.js application:

```shell theme={null}
tar --exclude='node_modules' --exclude='.next' --exclude='.git' -czvf myapp.tar.gz .
```

For a Python or FastAPI application:

```shell theme={null}
tar --exclude='__pycache__' --exclude='.venv' --exclude='.git' -czvf myapp.tar.gz .
```

## 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](#find-your-agent-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.

<img src="https://mintcdn.com/writer/Pg4chRA0RJ6SI8gu/images/home/agent-builder/agents-tab.png?fit=max&auto=format&n=Pg4chRA0RJ6SI8gu&q=85&s=9bdc1bc47fd7b1c6a40f787459bd3465" alt="" width="2910" height="1800" data-path="images/home/agent-builder/agents-tab.png" />

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.

<img src="https://mintcdn.com/writer/Pg4chRA0RJ6SI8gu/images/home/agent-builder/agents-tags.png?fit=max&auto=format&n=Pg4chRA0RJ6SI8gu&q=85&s=05a182b1eea814cfc9e79762188a9c7e" alt="" width="2910" height="758" data-path="images/home/agent-builder/agents-tags.png" />

### 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**.

<img src="https://mintcdn.com/writer/Pg4chRA0RJ6SI8gu/images/home/agent-builder/agents-bulk-actions.png?fit=max&auto=format&n=Pg4chRA0RJ6SI8gu&q=85&s=1f434b07a081bd92786886e486b4dd2f" alt="" width="2910" height="1800" data-path="images/home/agent-builder/agents-bulk-actions.png" />

<Tip>
  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.
</Tip>

## 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:

| Setting       | Description                                                                                                                                       | Default                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Instance size | vCPU, RAM, and disk allocated to your container                                                                                                   | Small: 1 vCPU, 2 GB RAM, 10 GB disk |
| Sleep timeout | How long the container stays warm before going idle. Lower means lower cost and longer cold starts; higher means faster response and higher cost. | 15 minutes                          |
| Default port  | The port your application listens on inside the container. Port 8001 is reserved.                                                                 | Port 8000                           |

3. Select **Save**. The settings apply to the latest version in that environment.

<img src="https://mintcdn.com/writer/Pg4chRA0RJ6SI8gu/images/home/agent-builder/configure-deployment.png?fit=max&auto=format&n=Pg4chRA0RJ6SI8gu&q=85&s=fa5ce9180ac8ab43b81a059d517bbc00" alt="" width="2910" height="1800" data-path="images/home/agent-builder/configure-deployment.png" />

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.

<img src="https://mintcdn.com/writer/Pg4chRA0RJ6SI8gu/images/home/agent-builder/change-deployment-url.png?fit=max&auto=format&n=Pg4chRA0RJ6SI8gu&q=85&s=ad9d57543249944a3288401facbd166e" alt="" width="2910" height="1800" data-path="images/home/agent-builder/change-deployment-url.png" />

## 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.

<img src="https://mintcdn.com/writer/Pg4chRA0RJ6SI8gu/images/home/agent-builder/generate-api-key.png?fit=max&auto=format&n=Pg4chRA0RJ6SI8gu&q=85&s=13f6294baa28d51af091c5c19dfdf1d0" alt="" width="2910" height="1800" data-path="images/home/agent-builder/generate-api-key.png" />

### 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.

```shell theme={null}
curl -X POST https://<YOUR-AGENT-ENV-URL>/<PATH-EXPOSED-BY-DEPLOYED-AGENT> \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '<request body defined by your endpoint>'
```

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

* [Learn about Agent Builder v2](/home/agent-builder/overview) to understand supported frameworks, environments, and limitations.
* [Review key concepts](/home/agent-builder/overview#key-concepts) to understand environments, snapshots, and the promotion flow.