Skip to content

Agent layer tools

The event log and hosted tools that external agent processes (such as the Python agent layer) use.

6 tools in the agent category. Badges: read-only tools never change the project; mutating tools are undoable and attributed; open-world tools reach outside the engine and MCP clients ask before running them.

Tool Summary
events_poll Read the engine's live event stream (the same events the editor's Activity feed shows: tool calls with their actor, studio changes such as messages, tasks, feedback, decisions and loops, play state, selection, scene loads/saves, asset changes) after a cursor, without consuming them.
tool_host_register Offer tools implemented in your own process (a Python agent harness, a script) to every agent connected to this engine: each becomes an engine tool named py_<name> that appears in tools/list.
tool_host_poll Fetch the calls other agents made to your py_* tools (see tool_host_register): [{call, tool, args, actor}].
tool_host_reply Answer one call fetched with tool_host_poll.
tool_host_unregister Stop serving the py_* tools of a host (they disappear from tools/list; calls still waiting fail).
tool_host_list Which external processes serve py_* tools: each host's label, owner (actor), tools, queued and in-flight calls, calls served and seconds since its last poll; plus the event stream's cursor range (events_poll).

events_poll

Follow engine events read-only

Read the engine's live event stream (the same events the editor's Activity feed shows: tool calls with their actor, studio changes such as messages, tasks, feedback, decisions and loops, play state, selection, scene loads/saves, asset changes) after a cursor, without consuming them. Pass the returned next as since on the next call; since=0 starts with everything still retained (the last 4096 events). Filter with types ("tool", "studio", "studio.message", "play_state", ...), actors (prefix match, e.g. "mcp:sky-agents") or exclude_actors. wait_ms > 0 long-polls until a matching event arrives (agent socket connections only; use a dedicated connection, the wait blocks that connection). Example: {since: 120, types: ["studio.message"], wait_ms: 20000}.

Argument Type Required Description Values
since integer Cursor: the next of the previous call (0 = from the oldest retained event)
types string[] Only these event types ("type" or "type.kind", e.g. "studio.task")
actors string[] Only events whose actor starts with one of these
exclude_actors string[] Skip events whose actor starts with one of these (e.g. your own)
limit integer Max events returned (default 200, max 1000)
wait_ms integer Long-poll: wait up to this long for a matching event (max 25000, default 0) 
events_poll {"since": 0, "types": ["studio.message", "studio.task"]}

skywalker call events_poll '{"since": 0, "types": ["studio.message", "studio.task"]}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "events_poll",
    "arguments": {
      "since": 0,
      "types": [
        "studio.message",
        "studio.task"
      ]
    }
  }
}

tool_host_register

Serve tools from your process mutating

Offer tools implemented in your own process (a Python agent harness, a script) to every agent connected to this engine: each becomes an engine tool named py_ that appears in tools/list. Calls are queued for you; fetch them with tool_host_poll on a dedicated connection and answer each with tool_host_reply. Keep polling: a host that has not polled for ttl_seconds (default 60) is dropped with its tools. Re-register with the returned host id to change the tool set. Example: {label: "sky-agents memory", tools: [{name: "memory_recall", description: "Search the team's shared memory", input_schema: {type: "object", properties: {query: {type: "string"}}, required: ["query"]}}]}.

Argument Type Required Description Values
tools object[] yes The tools to serve
tools[].name string yes Tool name (py_ is prepended)
tools[].title string Short title
tools[].description string What it does, for language models
tools[].input_schema object JSON Schema of the arguments
tools[].mutates boolean Changes the project or game (default false)
tools[].capabilities object Engine tools it calls back into while serving a call: {calls: [names or globs], mutate, network} (docs/CUSTOM_TOOLS.md); callbacks pass _meta["skywalker/call_id"]
tools[].limits object {timeout_ms, max_output_bytes, max_calls}
host string Your host id from an earlier registration (to update its tool set)
label string Who serves these tools, shown in descriptions and tool_host_list
ttl_seconds number Drop this host after this long without a poll (30-3600, default 60)
replace boolean Take over names another host serves (default false) 
tool_host_register {"tools": [{"name": "memory_recall", "description": "Search shared memory"}]}

skywalker call tool_host_register '{"tools": [{"name": "memory_recall", "description": "Search shared memory"}]}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_host_register",
    "arguments": {
      "tools": [
        {
          "name": "memory_recall",
          "description": "Search shared memory"
        }
      ]
    }
  }
}

tool_host_poll

Fetch calls for your tools read-only

Fetch the calls other agents made to your py_* tools (see tool_host_register): [{call, tool, args, actor}]. wait_ms long-polls until a call arrives (default 20000, max 25000); use a connection dedicated to polling. Answer every call with tool_host_reply. Polling also keeps your host alive.

Argument Type Required Description Values
host string yes Your host id
wait_ms integer Wait up to this long for a call (default 20000, max 25000)
max integer Max calls returned (default 8, max 64) 
tool_host_poll {"host": "host"}

skywalker call tool_host_poll '{"host": "host"}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_host_poll",
    "arguments": {
      "host": "host"
    }
  }
}

Minimal call with the required arguments; see the table for everything else.

tool_host_reply

Answer a tool call read-only

Answer one call fetched with tool_host_poll. Give text (what the calling model reads), optionally structured JSON and PNG images (base64), and is_error=true when the call failed (say why in text, with a hint).

Argument Type Required Description Values
host string yes Your host id
call integer yes The call id from tool_host_poll
text string The result as text
structured object Machine-readable result
images string[] PNG images, base64
is_error boolean The call failed 
tool_host_reply {"host": "host", "call": 1}

skywalker call tool_host_reply '{"host": "host", "call": 1}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_host_reply",
    "arguments": {
      "host": "host",
      "call": 1
    }
  }
}

Minimal call with the required arguments; see the table for everything else.

tool_host_unregister

Stop serving tools mutating

Stop serving the py_* tools of a host (they disappear from tools/list; calls still waiting fail). Hosts that stop polling expire on their own after ttl_seconds.

Argument Type Required Description Values
host string yes Host id 
tool_host_unregister {"host": "host"}

skywalker call tool_host_unregister '{"host": "host"}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_host_unregister",
    "arguments": {
      "host": "host"
    }
  }
}

Minimal call with the required arguments; see the table for everything else.

tool_host_list

Tool hosts read-only

Which external processes serve py_* tools: each host's label, owner (actor), tools, queued and in-flight calls, calls served and seconds since its last poll; plus the event stream's cursor range (events_poll).

Takes no arguments.

tool_host_list {}

skywalker call tool_host_list '{}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_host_list",
    "arguments": {}
  }
}