Skip to content

GrayGooAgent Install and Quickstart

Scope

This guide is for the first successful run on the current validated launch target:

  • Unreal Engine 5.7
  • Windows / Win64 editor workflow
  • GrayGooAgent as an editor-only plugin

If you are testing a different engine version or platform, treat this guide as a reference, not a compatibility promise.

What You Need

  • A project running in UE 5.7
  • The GrayGooAgent plugin installed through Fab or copied into <Project>/Plugins/GrayGooAgent
  • Internet access for your selected LLM provider
  • One working provider credential path:
  • API key, or
  • ChatGPT Plus/Pro login for the Codex provider path

Install Checklist

1. Install the Plugin

Use one of these paths:

  • Fab install into your engine, then enable the plugin in the target project
  • Copy the packaged GrayGooAgent plugin folder into <Project>/Plugins/

After installation, open the project and confirm GrayGooAgent is enabled.

2. Confirm Unreal Plugin Dependencies

For the narrowest first successful run, manually confirm these editor plugins:

  • Interchange
  • PythonScriptPlugin

If either of them was disabled, restart the editor after enabling it.

GrayGooAgent also declares broader capability-side editor dependencies for specific workflow surfaces:

  • Niagara
  • PCG
  • Dataflow

These are not the first-run onboarding focus. Treat them as capability dependencies that matter when you are specifically using those workflow surfaces. If one of them is unavailable, the related action set may be reduced even though the basic onboarding path can still succeed.

3. Open the Panel

Open the panel from:

  • Window > GrayGooAgent

The plugin settings page lives at:

  • Project Settings > Plugins > GrayGooAgent

You can also use the startup guide card inside the panel and click Open Settings.

For launch, keep the first setup narrow and simple:

  • Configure one provider instance first
  • Set both Default Provider Instance and Default Lightweight Provider Instance to that same instance
  • Leave Instruction Paths empty unless you already have a known-good prompt library
  • Leave Enable External Agent Bridge off unless you specifically need outside tools to drive the editor
  • Leave mutating workflows for later; start with the built-in read-only quickstart

Provider Setup: Simplest Path

The safest onboarding path is one provider instance with explicit settings.

Recommended fields for the first working setup:

  • Instance Name: any clear name such as Primary OpenAI
  • Provider ID: the provider template that matches your endpoint, for example openai or openai-compatible
  • Model ID: your chosen model, for example gpt-5.4-mini
  • API Endpoint: the full endpoint for that provider
  • Auth: your API key or login-backed credential flow

If you want the smallest number of moving parts, start with a standard OpenAI or OpenAI-compatible endpoint, then verify that the startup guide reports the provider as ready before trying anything else.

First Successful Run

1. Start a Fresh Session

Open the GrayGooAgent panel and create a fresh session.

The startup guide card will check:

  • provider readiness
  • required plugin dependencies
  • custom instruction paths
  • external bridge state
  • quickstart readiness

2. Clear Any Blocking Issues

If the guide shows [BLOCK], fix those items first.

If it shows only [WARN], core chat may already be usable, but you should still understand the warning before moving on.

3. Run the Built-In Quickstart

Use one of these actions from the guide card:

  • Insert Quickstart
  • Run Quickstart

Run Quickstart is the fastest path when the current session is ready.

The built-in quickstart is intentionally read-only. It asks GrayGooAgent to:

  • report the active agent, provider, and model
  • list the first actors in the current level
  • describe read-only Unreal actions it can use right now
  • suggest a few safe next tasks without making changes

4. What Success Looks Like

Your first run is healthy when all of these are true:

  • the panel opens normally
  • the startup guide has no blocking provider error
  • Run Quickstart is enabled or Insert Quickstart produces a coherent read-only response
  • the response correctly identifies the active provider and model
  • the response can inspect real editor context such as the current level or current actors

After the read-only quickstart succeeds, try one small grounded task:

  • inspect one Blueprint
  • search for one asset by name
  • inspect the current level or actor list
  • capture one screenshot for visual verification

Do not start with broad write requests. First confirm that the project context and provider path are both stable.

Optional Advanced Settings

You do not need these for the first run, but they are available:

  • Instruction Paths Add custom prompt or instruction directories after the default path already works.
  • Enable Python Execute Tool Enables mutating Unreal Editor Python execution. Only turn this on when you intentionally want Python-backed editor changes.
  • Expose Screenshot Tool To Remote Providers Advanced option for broader remote-tool workflows.
  • Enable External Agent Bridge Allows external tools to drive the editor through the bridge service. This requires a restart to apply.

External Agent Workflow Path

If you want external agents to drive Unreal Editor through GrayGooAgent, the recommended companion integration path is:

  • graygoo-unreal-bridge
  • packaged inside the GrayGooAgent plugin at Docs/graygoo-unreal-bridge/

This companion skill is meant to sit on the external-agent side and wrap:

  • editor status checks
  • bridge readiness checks
  • task execution
  • wait / polling flow
  • safe stop or restart behavior

Use this path only after the normal in-editor quickstart already works. For the first external-agent success:

  • keep one provider instance configured
  • enable Enable External Agent Bridge
  • restart the editor
  • verify the startup guide shows the bridge as healthy
  • send one narrow task and wait for completion before reusing the session

If you are preparing a broader external-agent workflow, read:

If Something Fails

Go to:

Start with the section that matches the startup guide status:

  • Provider
  • Plugin Dependencies
  • Instructions
  • External Bridge
  • Quickstart