TypeStack Magic – How to talk to the Agent

The TypeStack Magic prompt field is more than a text box. Under the hood it can trigger tools, write files, and create new CMS pages – as long as you give it clear, structured instructions.

There are three main ways to talk to the Agent:

  1. Special commands like TEST and FILE-TEST.
  2. JSON with aOperations (the real power).
  3. Plain text, which is simply echoed back (for quick experiments).

Special commands

For quick checks you can use two built-in commands without JSON:

  • TEST – end-to-end health check.
    Returns a JSON response with sMode = "test" and confirms that the AJAX and JSON pipeline is working.

  • FILE-TEST – filesystem self-test.
    Writes a small test file to data/agent/fs-test.txt using the AgentToolFileSystem tool, and returns detailed debug info.

If both work, the Agent stack (routing + JSON + filesystem) is functioning correctly.

JSON mode with aOperations

For real work, the Agent expects a JSON object in the prompt. The root object contains an array called aOperations. Each entry in that array is one operation.

Each operation contains:

  • sTool – which tool to call (for example "fs", "page", "env").
  • sMode – what that tool should do.
  • Additional fields – for example aArgs, sBase, sPath, sContent, depending on the tool.

The Agent executes each operation in order and returns a JSON response that always includes:

  • Your original aOperations (what you asked for).
  • An aOpResults block with the result and debug lines per operation.

Available tools

Currently, the Agent supports three tools:

  • fs – filesystem helper (read, write, append, replace) in safe, sandboxed paths.

  • page – CMS page operations (currently: create a page; gradually extended towards full CRUD).

  • env – environment info from the current TypeStack session or a simple ping.

New tools can be added by implementing AgentTool* classes and wiring them into AgentPrompt::HandlePrompt().