> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/19.latest/add-ons/deploy/deploying-entities.md).

# Deploying Entities

Deploy AI connections, profiles, prompts, and agents between environments using Umbraco Deploy.

This guide walks you through deploying AI configuration between environments.

## Deployment Workflow

AI entities follow the same deployment workflow as Umbraco content types and other configuration:

1. **Create/Edit** - Make changes in the Umbraco backoffice
2. **Save** - Deploy automatically creates deployment files
3. **Commit** - Commit deployment files to version control
4. **Deploy** - Push to other environments (Umbraco Deploy handles the rest)

## What Gets Deployed

### Connections

When you save a Connection, Deploy creates a file like:

```
data/Revision/umbraco-ai-connection__openai-production_abcd1234.uda
```

**Contains:**

* Connection name and alias
* Provider ID
* Connection settings (with sensitive data filtered)
* Active status

**Environment resolution:**

* API keys resolve from each environment's `appsettings.json`
* Provider must be installed in target environment

### Profiles

When you save a Profile, Deploy creates a file like:

```
data/Revision/umbraco-ai-profile__chat-assistant_abcd1234.uda
```

**Contains:**

* Profile name and alias
* Capability (Chat, Embedding, SpeechToText, or the experimental ImageGeneration, Decision, and Extraction)
* Model provider ID and model ID
* Capability-specific settings
* Connection reference (UDI)
* Tags

**Dependencies:**

* Automatically deploys the referenced Connection first
* For chat profiles, any referenced Guardrails are deployed first

### Contexts

When you save a Context, Deploy creates a file like:

```
data/Revision/umbraco-ai-context__brand-voice_abcd1234.uda
```

**Contains:**

* Context name and alias
* Context resources (serialized as JSON)

### Guardrails

When you save a Guardrail, Deploy creates a file like:

```
data/Revision/umbraco-ai-guardrail__safety-checks_abcd1234.uda
```

**Contains:**

* Guardrail name and alias
* Rules (serialized as JSON)

### Settings

AI Settings is a singleton entity. When saved, Deploy creates a file like:

```
data/Revision/umbraco-ai-settings__ai-settings_abcd1234.uda
```

**Contains:**

* Default chat profile reference (optional)
* Default embedding profile reference (optional)
* Classifier chat profile reference (optional)
* Default Image Generation profile reference (optional, experimental)
* Default Decision profile reference (optional, experimental)
* Default Extraction profile reference (optional, experimental)

**Dependencies:**

* Any referenced profiles are deployed first
* A reference to a profile that is missing on the target, or whose capability doesn't match the setting, is left empty. The import does not fail.

### Prompts (Requires Umbraco.AI.Prompt.Deploy)

When you save a Prompt, Deploy creates a file like:

```
data/Revision/umbraco-ai-prompt__article-summarizer_abcd1234.uda
```

**Contains:**

* Prompt name, alias, and description
* Instructions (template content, may include `{{placeholders}}`)
* Profile reference (if specified)
* Context IDs and Guardrail IDs
* Scoping rules
* Option count, IncludeEntityContext flag, IsActive flag
* Tags

**Dependencies:**

* If linked to a Profile, deploys the Profile first
* Any referenced Guardrails are deployed first

### Agents (Requires Umbraco.AI.Agent.Deploy)

When you save an Agent, Deploy creates a file like:

```
data/Revision/umbraco-ai-agent__content-helper_abcd1234.uda
```

**Contains:**

* Agent name, alias, description, and agent type (`Standard` or `Orchestrated`)
* Type-specific configuration (serialized as JSON):
  * **Standard agents**: Instructions, allowed tool IDs, allowed tool scope IDs, context IDs, per-user-group permission overrides, optional output schema
  * **Orchestrated agents**: Workflow ID and workflow-specific settings
* Surface IDs and scoping rules
* Guardrail IDs
* Profile reference (if specified)
* IsActive flag

**Dependencies:**

* If linked to a Profile, deploys the Profile first
* Any referenced Guardrails are deployed first

{% hint style="warning" %}
For **orchestrated agents**, the workflow implementation must be registered in the target environment. Deploy transfers the workflow ID and settings, but the workflow code itself must be deployed as part of the application.
{% endhint %}

{% hint style="info" %}
Standard agent `UserGroupPermissions` are deployed by user group alias, because user group keys differ between environments. On import, each alias is matched to the user group with the same alias in the target environment.

User groups are not added as explicit Deploy dependencies. Create them in the target environment before deploying agents that reference them.
{% endhint %}

{% hint style="warning" %}
If an agent denies tools for a user group that doesn't exist in the target environment, the import fails. Deploy doesn't drop a deny, because that would give the group's users tools you withheld. Create the user group with the same alias, then deploy the agent again.
{% endhint %}

## Step-by-Step: Deploying a Connection

### 1. Create Connection in Development

1. Open the Umbraco backoffice
2. Navigate to **Settings → AI → Connections**
3. Click **Create Connection**
4. Select provider (e.g., OpenAI)
5. Enter details:
   * **Name:** "OpenAI Production"
   * **Alias:** "openai-production"
   * **API Key:** `$Umbraco:AI:Secrets:OpenAIApiKey` (configuration reference)
   * **Organization ID:** (optional)
6. Click **Save**

### 2. Verify Deployment File

Check that the deployment file was created:

```bash
# File location (example)
data/Revision/umbraco-ai-connection__openai-production_abc123.uda
```

Open the file and verify it contains the configuration reference, not the actual API key:

```json
{
  "Settings": {
    "apiKey": "$Umbraco:AI:Secrets:OpenAIApiKey"
  }
}
```

### 3. Commit to Version Control

```bash
git add data/Revision/umbraco-ai-connection__openai-production_*.uda
git commit -m "feat(ai): Add OpenAI production connection"
git push
```

### 4. Configure Target Environment

Before deploying, ensure the target environment has the configuration:

**appsettings.Production.json:**

```json
{
  "Umbraco": {
    "AI": {
      "Secrets": {
        "OpenAIApiKey": "sk-prod-xyz789..."
      }
    }
  }
}
```

### 5. Deploy to Target Environment

When you deploy to the target environment (via Umbraco Cloud, Azure DevOps, or other CI/CD):

1. Umbraco Deploy detects the new deployment file
2. Creates the Connection in the target environment
3. Resolves `$Umbraco:AI:Secrets:OpenAIApiKey` from the target's `appsettings.json`
4. Activates the Connection

Sensitive literal values, such as an API key typed directly into the field, are never deployed. The target environment keeps its own value for those fields.

If the target has no value for a required secret, the Connection is imported as inactive. Enter the secret on the target environment, then activate the Connection. For details, see [Configuration](/ai-in-umbraco/19.latest/add-ons/deploy/configuration.md).

## Step-by-Step: Deploying a Profile

### 1. Create Profile in Development

1. Navigate to **Settings → AI → Profiles**
2. Click **Create Profile**
3. Enter details:
   * **Name:** "Chat Assistant"
   * **Alias:** "chat-assistant"
   * **Connection:** Select "OpenAI Production"
   * **Model:** "gpt-4o"
   * **Temperature:** 0.7
4. Click **Save**

### 2. Verify Deployment Files

Check that both files exist:

```bash
# Profile deployment file
data/Revision/umbraco-ai-profile__chat-assistant_abc123.uda

# Connection deployment file (if not already committed)
data/Revision/umbraco-ai-connection__openai-production_def456.uda
```

### 3. Commit and Deploy

```bash
git add data/Revision/umbraco-ai-profile__chat-assistant_*.uda
git commit -m "feat(ai): Add chat assistant profile"
git push
```

When deployed, Umbraco Deploy:

1. Deploys the Connection first (if not already deployed)
2. Deploys the Profile
3. Links the Profile to the Connection

## Multi-Environment Example

Here's how the same configuration deploys to different environments:

### Development Environment

**appsettings.Development.json:**

```json
{
  "Umbraco": {
    "AI": {
      "Secrets": {
        "OpenAIApiKey": "sk-dev-abc123..."
      }
    }
  }
}
```

### Staging Environment

**appsettings.Staging.json:**

```json
{
  "Umbraco": {
    "AI": {
      "Secrets": {
        "OpenAIApiKey": "sk-staging-def456..."
      }
    }
  }
}
```

### Production Environment

**appsettings.Production.json:**

```json
{
  "Umbraco": {
    "AI": {
      "Secrets": {
        "OpenAIApiKey": "sk-prod-xyz789..."
      }
    }
  }
}
```

### Deployment File (Same for All Environments)

**umbraco-ai-connection\_\_openai-production\_abc123.uda:**

```json
{
  "Name": "OpenAI Production",
  "Alias": "openai-production",
  "ProviderId": "openai",
  "Settings": {
    "apiKey": "$Umbraco:AI:Secrets:OpenAIApiKey"
  }
}
```

Each environment resolves `$Umbraco:AI:Secrets:OpenAIApiKey` from its own configuration, so the same deployment file works everywhere.

## Deployment Order

Deploy handles dependencies automatically, but it's helpful to understand the order:

1. **Connections, Contexts, Guardrails** (no dependencies on other AI entities)
2. **Profiles** (depend on Connections, plus any referenced Guardrails)
3. **Prompts, Agents, Settings** (optionally depend on Profiles, plus any referenced Guardrails)

If you deploy a Profile, Deploy ensures its Connection is deployed first. If you deploy an Agent or Prompt, Deploy ensures its Profile (and the Profile's Connection) are deployed first.

## Troubleshooting

### Deployment Fails: "Connection not found"

If deployment fails because a Connection doesn't exist:

1. Check that the Connection deployment file exists in `data/Revision/`
2. Verify the Connection file was committed to version control
3. Deploy the Connection before deploying Profiles/Prompts/Agents

### Deployment Fails: "Provider not found"

If deployment fails because a provider isn't found:

1. Ensure the provider package is installed in the target environment (e.g., `Umbraco.AI.OpenAI`)
2. Rebuild and restart the target environment

### API Keys Not Resolving

If the target environment doesn't resolve `$` references:

1. Verify the configuration key exists in `appsettings.json`
2. Check the configuration path matches exactly (case-sensitive)
3. Restart the application

### User Group Permissions Missing on Agents

Standard agent `UserGroupPermissions` are deployed by user group alias but are not tracked as explicit Deploy dependencies. If an agent's user group permissions appear empty or incorrect after deployment:

1. Ensure referenced user groups exist in the target environment
2. Confirm user groups have the same alias across environments
3. Create user groups before deploying Agents that reference them

An entry that only allows tools for a missing user group is dropped. An entry that denies tools for a missing user group fails the import.

## Next Steps

* [Best Practices](/ai-in-umbraco/19.latest/add-ons/deploy/best-practices.md) - Security and workflow recommendations
* [Configuration](/ai-in-umbraco/19.latest/add-ons/deploy/configuration.md) - Configure sensitive data filtering


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/19.latest/add-ons/deploy/deploying-entities.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.