Tokomono
Ai Suite
4. Prompting

Advanced Prompting

Advanced Prompting & CRAFT Engine

In AI Suite, Agents construct their system prompts using the CRAFT Framework (Context, Role, Action, Format, Target & Tone). Reusable Roles and Tones & Targets are managed centrally in the UI and can be shared across multiple agents, while CraftPromptable compiles the 5 sections into a structured markdown system prompt:

### CONTEXT:
...

### ROLE:
...

### ACTION:
...

### FORMAT:
...

### TARGET & TONE:
...

Try it in the UI:

1. Step-by-Step: Creating, Editing & Deleting a Role (/ai-suite#/roles)

A Role defines who the AI agent is (its persona and behavioral traits) and populates the ### ROLE: section of the compiled system prompt.

Creating a New Role

  1. In the top navigation bar, click Agents ▾ and select Roles.
  2. Click the blue New Role button in the top-right corner to open the Create Role modal.
  3. Fill in the three fields:
    • Name: A short, recognizable label displayed in UI tables, agent badges, and role dropdowns (e.g., Claims Specialist or Senior Copywriter).
    • Role (e.g. Copywriter): The actual instruction text injected into the agent's ### ROLE: prompt section (e.g., You are a senior insurance claims handler who evaluates damaged package claims accurately and fairly.).
    • Characteristic (e.g. Writes clearly): A brief summary of the role's key traits displayed in the Roles overview table (e.g., Analytical, objective, policy-driven).
  4. Click Save.

Editing a Role

  1. On /ai-suite#/roles, click the blue pencil icon on the right side of the role's row.
  2. Update the Name, Role, or Characteristic in the Edit Role modal and click Save.
  3. Any agent linked to this role automatically inherits the updated ### ROLE: text.

Deleting a Role

  1. Click the red trash icon on the right side of the role's row and confirm deletion in the dialog.
  2. Dependency Protection: If the role is still assigned to one or more agents, the server returns a 409 Conflict and the UI opens a Cannot delete role alert listing every linked agent. Unlink or reassign the role on those agents first before deleting it.

2. Step-by-Step: Creating, Editing & Deleting a Tone & Target (/ai-suite#/tones)

A Tone & Target defines the voice, style, and target audience of the agent and populates the ### TARGET & TONE: section of the compiled system prompt.

Creating a New Tone

  1. In the top navigation bar, click Agents ▾ and select Tones & Targets.
  2. Click the blue New Tone button in the top-right corner to open the Create Tone modal.
  3. Fill in the fields:
    • Name: A short label for dropdowns and badges (e.g., Empathetic Customer Support or Formal Legal).
    • Tone & Target Description (e.g. Formal tone for legal team): The full instruction text injected into the agent's ### TARGET & TONE: section (e.g., Write in a warm, empathetic, and reassuring tone aimed at retail customers experiencing delivery issues.).
  4. Click Save.

Editing or Deleting a Tone

  • Edit: Click the blue pencil icon on a tone row, modify the Name or Tone & Target Description, and click Save.
  • Delete: Click the red trash icon on a tone row and confirm. If the tone is still linked to any agents, a dependency alert will list the linked items.

3. Step-by-Step: Organizing Agents with Folders (/ai-suite#/agents)

On the Agents overview page, you can organize your agents into hierarchical folders:

  1. Create a Folder:
    • Click the New Folder button in the top-right bar.
    • Enter a Folder Name in the modal and click Create (if you are currently inside a folder, the new folder is created as a subfolder).
  2. Navigate Folders:
    • Click any folder row to open it.
    • Click the .. (Up to parent folder) row or the ← Back button next to the page title to return to the parent folder.
  3. Move an Agent into a Folder:
    • Drag & Drop: Grab an agent row by its drag handle (⋮⋮ on the left of the agent name) and drop it onto a folder row (or onto the .. row to move it up to the parent folder).
    • Move Modal: Alternatively, click the Move to Folder (⇄) icon in the agent's Actions column, select Root or a target folder in the Move Agent modal, and click Move.
  4. Rename or Delete a Folder:
    • Click the pencil icon on a folder row to rename it.
    • Click the red trash icon to delete a folder. (Note: A folder must be empty—containing no agents or subfolders—before it can be deleted.)

4. Step-by-Step: Creating & Editing an Agent with the CRAFT Editor

Creating a New Agent in the UI

  1. Navigate to Agents ▾ → Agents.
  2. Click the blue + New Agent button in the top-right corner.
  3. In the Create New Agent modal, enter the agent's Name and click Create.
  4. The agent is created in the current folder with a unique 8-character sync_hash, and you are automatically redirected to the Edit Agent screen (/ai-suite#/agent/{id}/edit).

Configuring the CRAFT Prompt (/ai-suite#/agent/{id}/edit)

You can reach the CRAFT editor at any time by clicking the Edit Prompt (pencil/document) icon on /ai-suite#/agents or clicking Edit Prompt inside the system prompt card on /ai-suite#/agent/{id}.

The Edit Agent screen features a split view:

  1. Left Panel — CRAFT Prompt Engine:
    • Agent Name: The display name of the agent.
    • Structured Output (JSON): Check this box if the agent returns structured JSON data (enables using this agent inside Enum workflow nodes and matching JSON keys in Statement nodes).
    • Context (Background info, e.g., rules, facts): Enter domain rules, policies, or background knowledge (### CONTEXT:).
    • Role (Who is the agent?): Select a reusable Role from the dropdown (### ROLE:), or -- None --.
    • Action (What precisely should the agent do?): Describe the exact task or instructions the agent must execute (### ACTION:).
    • Format (How should the answer look?): Specify output formatting requirements, such as markdown structure, length limits, or JSON fields (### FORMAT:).
    • Tone & Target (Voice and audience): Select a reusable Tone from the dropdown (### TARGET & TONE:), or -- None --.
  2. Right Panel — Live System Prompt Preview & Runtime Variables:
    • As you edit any CRAFT field or switch Role/Tone dropdowns, the Live System Prompt Preview updates immediately to show the exact compiled markdown prompt.
    • Dynamic Variables ({{...}}): You can include placeholders like {{customer_name}} or {{node_php}} anywhere in your CRAFT sections. All detected placeholders are automatically highlighted in purple in the preview and listed at the top of the preview panel under Variables expected at runtime.
  3. Saving Changes:
    • Click the purple Save Changes button in the top-right corner.

5. Exporting UI Agents to PHP Code & Syncing Code Agents

AI Suite supports both Database (Custom) Agents created in the UI and Imported (External) Agents backed by PHP classes in app/Ai/Agents:

  • Exporting a UI Agent to PHP (Export to Code):
    1. Open a UI-created agent in the CRAFT editor (/ai-suite#/agent/{id}/edit).
    2. Click Export to Code in the top-right bar and confirm in the dialog.
    3. AI Suite generates app/Ai/Agents/{StudlyName}.php implementing Laravel\Ai\Contracts\Agent and using the App\Ai\Concerns\CraftPromptable trait (context(), role(), action(), format(), target()), and converts the agent into an Imported agent.
  • Editing an Imported Agent: When an agent has the amber Imported badge, saving changes in /ai-suite#/agent/{id}/edit updates both the database version and writes the updated CRAFT sections directly back to the PHP class file.
  • Syncing Agents from Code (Sync Agents): On /ai-suite#/agents, click the indigo Sync Agents button in the top-right bar to scan config('ai-suite.agent_directories') (app/Ai/Agents), import new PHP agent classes, and synchronize existing code agents (including auto-creating missing Role and Tone records).