# Deploy an AI agent (/guides/deploy-an-agent)



This tutorial takes you from a signed-in account to a running AI agent with a
chat UI, a spending limit, and a clean shutdown. It takes about ten minutes.
You will use the **Alternate Agent** template, which bills its model usage to
your Alternate Clouds credits, so no third-party AI keys are needed.

The agent is a composite template (the agent plus its own PostgreSQL database),
and composite templates deploy from the web app only; the CLI does not support
them yet. Everything after the deploy works from the CLI.

## Before you start [#before-you-start]

* You have finished the [Quick start](/guides/quickstart): `acc` is installed,
  you are logged in, and a project is active (`acc whoami` shows it).
* You are signed in to the web app at `https://clouds.alternatefutures.ai`
  with the same account.
* Your organization has credits or an active trial.

## 1. Look at the template [#1-look-at-the-template]

```bash
acc templates info alternate-agent
```

The output lists the resources (1 vCPU, 2 GiB memory, 2 GiB storage), the
port, and the environment variables. Two of them are filled in by the platform
when you deploy:

| Variable     | What the platform does                                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `AF_API_KEY` | Creates a scoped access token for the agent. The agent uses it to pay for chat, image, and video inference from your credits. |
| `AF_ORG_ID`  | Fills in your organization id.                                                                                                |

Everything else has a default. You will set `AGENT_NAME` and
`AGENT_INSTRUCTIONS` to make it yours.

## 2. Deploy from the web app with a budget cap [#2-deploy-from-the-web-app-with-a-budget-cap]

1. Open **Deploy a template** at `https://clouds.alternatefutures.ai/deploy`
   and choose **Alternate Agent**.
2. Set `AGENT_NAME` (for example `Atlas`) and `AGENT_INSTRUCTIONS` (for example
   `You are a concise assistant for the Atlas project.`). Leave `AF_API_KEY`
   and `AF_ORG_ID` as the platform pre-fills them.
3. Under **Budget Cap**, set a **Monthly limit** of 20. The platform stops the
   service once it has spent 20 dollars in a month; your machine is not
   involved.
4. Deploy.

The template creates two services in your project, the agent and its database.
The deployment now goes through placement and start;
[How a deployment works](/guides/how-deployments-work) explains each stage.

## 3. Watch it come up [#3-watch-it-come-up]

```bash
acc services list
```

Run it again every twenty seconds or so until the agent service shows as
active with a URL of the form `https://my-agent-app.alternatefutures.ai`. If it
is still waiting after a few minutes, see
[The deployment stays in a waiting or creating state](/troubleshooting#the-deployment-stays-in-a-waiting-or-creating-state).

To see the agent starting, use the id `acc services list` printed:

```bash
acc services logs <serviceId> --tail 100
```

## 4. Talk to it [#4-talk-to-it]

Open the URL from step 3 in a browser. The chat UI loads with the name you
set. Ask it something; the reply is billed to your credits through the token
the platform created for it, and you can see the charge later under
**Billing**, **Usage** in the web app.

## 5. Change it without redeploying by hand [#5-change-it-without-redeploying-by-hand]

Environment variables live on the service. To give the agent a different
personality:

```bash
acc services env set <serviceId> AGENT_INSTRUCTIONS "You answer only with haiku."
acc services deploy <serviceId>
```

The redeploy creates a new deployment; the URL does not change.

## 6. Shut it down [#6-shut-it-down]

Close both services the template created, so nothing keeps billing:

```bash
acc services list
acc services close <serviceId>   # once for the agent, once for its database
```

`acc services close` keeps the service definition so you can deploy it again
later. `acc services delete <serviceId>` removes it entirely.

## What you learned [#what-you-learned]

* Templates carry their own resources and declare the variables they need;
  some variables the platform fills in for you.
* Composite templates deploy from the web app; from then on the CLI manages
  their services like any other.
* A per-service budget cap is set at deploy time and enforced server-side.
* Configuration changes are environment variables plus a redeploy.
* Closing a service is how you stop paying for it.

## Next steps [#next-steps]

* [How a deployment works](/guides/how-deployments-work)
* [How billing works](/guides/how-billing-works)
* [Template catalog](/templates/catalog), every template with its variables
* [Docs for AI agents](/ai-agents), for running the CLI steps from CI or another agent