Skip to content

GrayGooAgent External Agent Bridge

Scope

This guide shows how to let an external agent drive Unreal Editor through GrayGooAgent.

The packaged skill bundle is included inside the packaged GrayGooAgent plugin at:

  • Docs/graygoo-unreal-bridge/
  • Docs/graygoo-unreal-bridge/SKILL.md

If you want another agent system to drive Unreal Editor through the local GrayGooAgent bridge, the recommended companion skill is:

  • graygoo-unreal-bridge

This is the companion bridge tool for external agents. It handles startup, connection, task execution, waiting for results, and safe shutdown so you do not have to wire those steps yourself.

If your external-agent environment expects skills to live in a separate skill directory, copy the whole packaged graygoo-unreal-bridge folder out of the plugin package into that environment and keep the same relative scripts/ layout.

What The Companion Skill Covers

The graygoo-unreal-bridge skill is intended to wrap the local HTTP bridge instead of forcing users to hand-write raw requests.

Typical operations include:

  • checking bridge and editor status
  • starting the editor and waiting for bridge readiness
  • sending one task to the current or a new session
  • waiting on the returned session_id and turn_id
  • safely stopping or restarting the editor-side workflow

In practice, this allows the bridge to be used through a higher-level tool interface rather than through manual low-level protocol operations.

Use the companion skill when you want to:

  • connect Codex-style or other external agents to Unreal Editor
  • keep multi-turn context across follow-up editor tasks
  • let outside agents inspect or advance editor-visible work
  • avoid hand-maintaining bridge lifecycle and polling logic

Before using the external-agent path:

  • get the normal in-editor quickstart working first
  • confirm one provider instance is healthy
  • keep Default Provider Instance and Default Lightweight Provider Instance simple and stable

Then:

  1. enable Enable External Agent Bridge
  2. restart the editor
  3. confirm the startup guide reports the bridge as healthy
  4. use the graygoo-unreal-bridge skill to check status or wait for readiness
  5. send one concrete task
  6. wait for a terminal result before sending a follow-up to the same session

For initial validation, use a small task with clear verification criteria, such as:

  • inspect the current level
  • list the main actors in the active map
  • inspect one Blueprint or asset
  • capture one screenshot for visual confirmation

First Success Criteria

The external-agent path is healthy when:

  • the bridge health check succeeds
  • the editor is reachable through the bridge
  • the first task returns a valid session_id
  • the returned turn_id can be waited on successfully
  • the result reflects real editor context

Important Boundaries

  • The bridge skill is a companion integration asset, not a replacement for the editor plugin itself.
  • The recommended path is still to validate the in-editor quickstart first.
  • Do not send concurrent requests to the same session_id.
  • External bridge workflows remain limited to the editor-side capability surface.
  • Python-backed mutating execution is still off by default unless you explicitly enable it.

If Something Fails

Check these first:

  • the bridge is enabled
  • the editor was restarted after changing bridge settings
  • the bridge port is free
  • the default bridge agent can resolve a configured provider
  • the current session is not already busy

Then refer to: