Run External AI Agents in the Unreal Assistant Panel

You can run your own AI agent, such as Claude Code or Codex, in the Unreal Assistant panel instead of the Unreal Assistant service. The panel looks the same, but your agent provides the replies, the model, and the tool calls, using your own account with that agent's provider. While an external agent is selected, the panel sends your chat to that agent, not to the Unreal Assistant service.

Use an external agent if you already work with one of these agents and want to keep your own model, settings, and subscription while you work in Unreal Editor.

Unreal Editor starts the agent as a local program and communicates with it over the Agent Client Protocol (ACP). The editor also connects the agent to its Unreal MCP server, so the agent can use the same tools as any other MCP client. For more information, see Unreal MCP.

The panel supports the following AI agents:

Prerequisites

Before you start, ensure you have:

• Enabled the Unreal Assistant and Unreal MCP plugins. Both are enabled by default.

• Enabled the All Toolsets plugin, or the specific toolset plugins your agent needs. Your agent needs toolsets to use editor tools.

• Confirmed the Unreal MCP server is running. By default, it starts with the editor, and you can check the Model Context Protocol settings in Editor Preferences. For more information, see Unreal MCP.

• Installed Node.js, if you use one of the npm adapters.

• Installed your agent's CLI and signed in to your own account. The adapter uses that sign-in. To sign in, run claude login for Claude Code or codex login for Codex.

• Installed the ACP adapter for your agent. For install commands, see the table above. After you install the adapter, restart the editor so it can find the adapter on your PATH.

Set Up Your Agent in the Unreal Assistant Panel

To run your own AI agent in the panel, open the panel, then turn on and approve your agent.

Open the Unreal Assistant Panel

To open the panel, in Unreal Editor's main menu, go to Window > Unreal Assistant, or click Assistant on the right side of the status bar at the bottom of the editor.

Turn On Your Agent

To turn on your agent, follow these steps:

1. Go to Edit > Editor Preferences. Under General settings, select Unreal Assistant.

2. Expand External Agent.

3. In the External Agent dropdown, select your agent (Claude Code, Codex, Cursor, OpenCode, or Custom).

   

   If you select Custom, two more fields appear, Custom Agent Command and Custom Agent Arguments. Don’t put credentials in either field. This text is visible in the panel and written to the editor log when the agent starts. To pass secrets, use the agent’s environment variables or its own config file instead.

4. Enable Use External Agent. When your agent is set up, External Agent Status shows the full path to the adapter or command the editor runs.

   If External Agent Status shows an error with an install command, restart the editor first. If the error is still there after you restart, run the listed install command in a terminal, then restart the editor again.

Approve Your Agent

The first time the editor runs an agent's command in a project (when you enable Use External Agent or change the agent), an approval prompt appears.

• If you click Allow, the editor saves your approval for this project and starts the agent in the panel.

• If you click Don't Allow, the editor turns Use External Agent off and keeps using the Unreal Assistant service.

After you allow the agent, External Agent Status shows Runs <path>.

Switch Agents in the Panel

The Agent selector in the top-left corner of the panel lists Unreal Assistant and each external agent. Agents whose adapter isn't installed are grayed out.

When you select an external agent, the panel asks you to confirm the switch. If you haven't approved that agent's command in this project yet, the approval prompt appears.

Selecting Unreal Assistant from the list switches the panel back to the Unreal Assistant service without a prompt. Each agent keeps its own chat history.

Prompt Your Agent

The prompt bar shows your agent's own settings, such as permission mode, model, and reasoning effort. These settings change when you switch agents. For example, Claude Code's prompt bar looks like this:

With Codex, the prompt bar shows Codex's settings:

The available permission modes (shield icon) depend on the selected agent. For example, Claude Code's modes are Manual, Accept edits, Plan, Auto, and Bypass permissions.

When you prompt the agent to work in or get information from the editor, it calls Unreal MCP tools. To see each call, expand Required Actions.

Set Up an Agent for Multiple Projects or a Team

To set the same agent for everyone who uses an engine install, or for all your projects, use an AIAssistant.json file instead of Editor Preferences.

To set up an agent with an AIAssistant.json file, follow these steps:

1. Create file named AIAssistant.json.

2. Add your agent's command to the file. For example:

   Python

   {
     "main_url": "https://dev.epicgames.com/embed-view/assistant/",
     "agent": { "command": "C:/path/to/claude-agent-acp.cmd", "arguments": [] }
   }

   Copy full snippet(4 lines long)

3. Save the file in one of these locations:

   •  Engine/Config/: applies to everyone who uses this engine install.

   •  %LOCALAPPDATA%\UnrealEngine\5.9\: applies to you, in this engine version.

   • %LOCALAPPDATA%\UnrealEngine\Common\: applies to you, in every engine version.

4. Restart the editor.

5. In Editor Preferences, check that External Agent Status shows which file is in use.

To change which MCP servers the panel passes to the agent, add an mcp_servers array to the file. It replaces the default list. If you leave it out, the agent gets this editor's Unreal MCP server. An empty array ([]) passes no servers.

Troubleshooting