Skip to content

GrayGooAgent Install & 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: Fab listing
  • 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 editor dependencies for specific feature areas:

  • Niagara
  • PCG
  • Dataflow

These dependencies are not part of the core initial setup path. They become relevant when you use the corresponding feature areas. If one of them is unavailable, the related tools may be limited while the basic onboarding path can still work.

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

To minimize configuration complexity, start with a standard OpenAI or OpenAI-compatible endpoint, then verify that the startup guide reports the provider as ready before trying anything else.

Minimum working example:

Instance Name: Primary OpenAI
Provider ID: openai
Model ID: gpt-5.4-mini
API Endpoint: https://api.openai.com/v1/responses
Auth: OPENAI_API_KEY or direct API key entry
Default Provider Instance: Primary OpenAI
Default Lightweight Provider Instance: Primary OpenAI

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], the core workflow may already be usable, but you should still confirm the meaning of 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 concrete task:

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

Avoid broad write requests at this stage. First confirm that both the project context and provider path are stable.

After the First Successful Run

Only after the quickstart is stable should you expand into:

  • custom instruction paths
  • Python-backed mutating workflows
  • lightweight provider specialization
  • external-agent bridge setup

Use these pages next instead of treating them as day-one requirements:

If Something Fails

Go to:

Start with the section that matches the startup guide status:

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

If you need a support-ready checklist, continue with Support.