Skip to content

GrayGooAgent External Bridge Skill

Scope

This guide describes the recommended external-agent integration path for 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 bridge-side workflow asset that pairs with the editor plugin. It keeps the core product inside the editor while giving external agents a clean way to start, connect, execute tasks, wait for results, and shut the editor down safely when needed.

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 makes the external-agent path feel closer to a real workflow integration and less like a low-level protocol exercise.

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 grounded task
  6. wait for a terminal result before sending a follow-up to the same session

For first success, keep the task narrow and easy to verify, 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: