Import props into Unreal

With agent imports turned on, an agent can ask Prophouse to import props into the Unreal project you have open. Your editor picks up the request, imports the props and everything they depend on (materials, textures), and the agent gets back the /Game object paths to spawn in the level. Nothing opens a dialog in your editor, and nothing already in your project is overwritten.

Requirements

• The Prophouse Unreal plugin is installed, and the project is open in the editor.
• The plugin is signed in (Sign in with browser) as the same Prophouse member who created the agent’s API key. An agent only drives editors signed in as its own member, never a teammate’s.
• Accept agent imports is turned on in that editor (see below). It is off by default.
• The Prophouse desktop app is installed on the same machine. The plugin uses it to transfer files and starts it when needed.
• The agent’s API key has write scope.

Turn on agent imports

1. In Unreal, open Editor Preferences and go to Plugins → Prophouse.

2. Under Agent imports, check Accept agent imports.

3. Optionally, under Pull, set Default Destination Root to the folder imports should land in. Agents can override it per import with target_root. If it is empty, imports go to /Game/Prophouse.

The setting is per project and per user. While it is on, the editor checks in with Prophouse every 15 seconds and runs any import an agent queued for this project. While it is off, the editor still reports that it is open, so the agent can tell you to turn the setting on instead of waiting.

The project name agents use is the plugin’s Project Key setting, or the .uproject name when that is blank.

How an import runs

1. The agent calls import_to_unreal with prop ids. Prophouse first checks that a ready editor exists for the project (the preflight). If not, the call fails at once with an error that says what to fix.

2. Prophouse queues an import job for that project. Your editor picks it up on its next check-in, within about 15 seconds.

3. The editor imports the props and their dependencies with the same pipeline as a manual pull from the plugin, and shows a notification when it starts and finishes.

4. import_to_unreal waits up to wait_seconds (default 25, maximum 50) for the job to finish and returns the import view. If the job is still running, the agent calls get_unreal_import with the job_id and wait_seconds until done is true.

5. The agent spawns each requested[].object_path with an editor-side tool, such as an Unreal MCP server or the editor’s Python API.

Check editors with list_unreal_editors

list_unreal_editors lists every editor signed in as you that checked in within the last 24 hours. For each one it reports the project, engine and plugin version, machine, default destination root, whether it is online, whether it is ready for agent imports, and problems.

An editor is ready when it is online, accepts agent imports, and can reach the desktop app. Each problem is an object with a code, a message and a fix:

Code	Meaning	Fix
EDITOR_OFFLINE	The editor has not checked in recently, or was closed.	Open the project in Unreal with the plugin signed in. It checks in within seconds.
AGENT_IMPORTS_DISABLED	The editor is open but Accept agent imports is off.	Turn on Accept agent imports in that editor.
DESKTOP_AGENT_UNAVAILABLE	The editor cannot reach the Prophouse desktop app, which it uses to transfer files. The message includes the editor’s last error when there is one.	Install or start the desktop app on that machine.
EDITOR_BUSY	The editor is already running another import. This is a notice only; the editor is still ready.	Nothing. New imports queue behind the running one.

The result also has ready_projects (the projects you can import into right now) and a hint with setup instructions when no editor is connected or none is ready.

import_to_unreal preflight errors

These come back as tool errors before anything is queued. None is retryable as-is; details.fix says what to change.

Code	Meaning	Fix
UNREAL_NOT_CONNECTED	No editor signed in as this member has checked in within 24 hours.	Install or update the plugin, open the project, sign in with the same member as the API key, and turn on Accept agent imports.
UNREAL_PROJECT_NOT_OPEN	You passed project, and no editor has that project.	Open it, or use a name from details.open_projects (currently open) or details.recent_projects.
UNREAL_PROJECT_AMBIGUOUS	You left out project, and editors are open on more than one project.	Pass project with one of details.projects.
UNREAL_EDITOR_OFFLINE	The project’s editor is not online. details.last_seen_at says when it last checked in.	Open the project in Unreal with the plugin signed in, then retry.
AGENT_IMPORTS_DISABLED	The editor is online but does not accept agent imports.	Turn on Accept agent imports in that editor, then retry.
DESKTOP_AGENT_UNAVAILABLE	The editor cannot reach the desktop app. details.last_error has the editor’s last error.	Install or start the desktop app on that machine, then retry.

Errors from creating the job itself, such as ENTRY_NOT_FOUND for an unknown prop id or VALIDATION for a bad target_root, come back unchanged.

When several editors are open on the same project, Prophouse prefers one that is not busy.

The import view

import_to_unreal, get_unreal_import and cancel_unreal_import all return the same shape:

{
  "job_id": 12,
  "project": "ColdStorage",
  "target_root": "/Game/Prophouse",
  "status": "done",
  "phase": "imported",
  "done": true,
  "requested": [
    { "entry_id": 5, "name": "SM_Crate", "object_path": "/Game/Prophouse/Meshes/SM_Crate.SM_Crate" }
  ],
  "imported": [
    { "asset_name": "SM_Crate", "package": "/Game/Prophouse/Meshes/SM_Crate", "object_path": "/Game/Prophouse/Meshes/SM_Crate.SM_Crate", "action": "add" }
  ],
  "unchanged": [],
  "kept_local": [],
  "failed_items": [],
  "failure_reason": null,
  "problem": null,
  "next_step": "Spawn requested[].object_path in the level."
}

Field	Meaning
phase	waiting_for_editor (queued), importing, imported, failed or cancelled. status carries the underlying job status.
done	true once the job is finished (imported, failed or cancelled). Stop polling then.
requested	One row per prop you asked for. object_path is filled in once the job is done, and null before that. These are the paths to spawn.
imported	Assets written to the project by this import, including dependencies.
unchanged	Assets that were already in the project with identical content.
kept_local	Assets that already existed in the project with different content. Your local file was kept.
failed_items	Assets that could not be imported, each with an error.
failure_reason	Why the whole job failed, when it did.
problem	{code, message, fix} when the job is stuck or failed. See below.
next_step	A plain-language instruction for what to do now.

An object path is the package path plus the asset name, for example /Game/Prophouse/Meshes/SM_Crate.SM_Crate. Always use the paths Prophouse returns rather than building them from the prop name: when a name is already taken in the folder, the imported package gets a suffix.

Conflicts keep your local files

An agent import never overwrites an asset you already have. If an asset exists at the destination with different content, the import keeps your version and lists it under kept_local. The matching requested[].object_path then points at your local asset. To get the library version instead, move or rename the local asset and import again, or pull it from the plugin yourself.

Waiting and stuck jobs

Pass wait_seconds (up to 50) to import_to_unreal or get_unreal_import to block until the job finishes. Large imports can take longer than one call, so keep calling get_unreal_import with wait_seconds while done is false. Each call counts as one agent call.

While a job is not finished, problem explains anything that is holding it up:

Code	Meaning	Fix
EDITOR_OFFLINE	The job is queued and no editor for the project is online.	Open the project. The job runs when the editor reconnects. Call cancel_unreal_import to give up on it.
AGENT_IMPORTS_DISABLED	The editor is online but does not accept agent imports.	Turn on Accept agent imports. The job then runs.
DESKTOP_AGENT_UNAVAILABLE	The editor cannot reach the desktop app.	Install or start the desktop app on that machine.
EDITOR_NOT_PICKING_UP	A ready, idle editor has not picked the job up within about three check-ins (at least 45 seconds). The message includes the editor’s last error when there is one.	Check the Unreal Output Log, category LogProphouse.
EDITOR_STALLED	The import has made no progress for 3 minutes.	Check the Unreal Output Log, category LogProphouse.
EDITOR_OFFLINE_MID_IMPORT	The editor went offline during the import.	Nothing to do right away. The import resumes the next time the editor starts, or goes back in the queue after 60 minutes.
IMPORT_FAILED	The editor could not complete the job. failure_reason says why.	Fix the cause, then call import_to_unreal again.

A job waiting behind another import in a busy editor is not a problem: next_step names the job it is waiting on.

Cancel an import

cancel_unreal_import cancels a job that is still waiting_for_editor. Once the editor has started it, the job cannot be cancelled remotely and the call fails with JOB_STATE. Cancelling a job that is already cancelled does nothing and returns its view.

Tip

You can also import from Python inside the editor without an agent or the Accept agent imports setting: unreal.get_editor_subsystem(unreal.PhEditorSubsystem).import_entries([12, 34], ""), then poll get_last_agent_import(). See Scripting the plugin.