Triformers

AI agent definitions for the Triform platform. This repository contains the character personalities, action tools, and flow configurations that power the Triformer agents.

Quick Start

# Install the CLI
pipx install triform-cli

# Authenticate
triform auth login

# Pull this project
triform projects pull <project-id>

# Start auto-sync
cd Triformers
triform projects watch

Architecture

Core Principle: Agents in Flows

Every agent should be wrapped in a flow. This is the canonical pattern:

Flow/
└── Agents/
    └── AgentName/
        ├── Actions/     # Tools the agent can use
        └── Flows/       # Sub-flows (which contain more agents)

This pattern enables:

Composability: Flows can be nested to any depth
Reusability: Agents can call other flows as tools
Separation: Each agent has its own context and toolbox

Directory Structure

Triformers/
├── .triform/                    # Sync configuration (don't edit)
│   └── config.json              # Project & org IDs
│
├── Agents/                      # Standalone agents (for development)
│   └── {AgentName}/
│       ├── prompts.json         # System prompt & personality
│       ├── settings.json        # Model configuration
│       ├── io.json              # Input/output schema
│       ├── nodes.json           # Tools (action references)
│       ├── readme.md            # Documentation
│       └── Actions/             # Agent's tools
│           └── {ActionName}/
│
├── Flows/                       # Production flows
│   └── {FlowName}/
│       ├── io.json              # Flow inputs/outputs
│       ├── nodes.json           # Components in this flow
│       ├── readme.md            # Documentation
│       └── Agents/              # Agents in this flow
│           └── {AgentName}/
│               ├── Actions/     # Agent's tools
│               └── Flows/       # Nested flows (sub-agents)
│
├── triggers/
│   ├── endpoints.json           # API endpoint configs
│   └── chat.json                # Chat interface settings
│
├── requirements.json            # Project requirements spec
└── {project}.env                # Environment variables

Nesting Example: Carta with Scout Team

Here's a real example of deep nesting - the Carta agent with its Scout Team:

Flows/Carta/                           # Carta Flow (entry point)
└── Agents/Carta/                      # Carta Agent (talks to users)
    ├── Actions/                       # Carta's tools
    │   ├── ask_user/
    │   ├── emote/
    │   ├── project_edit/
    │   └── build_project/
    │
    └── Flows/                         # Sub-flows (delegated work)
        └── Scout Team/                # Scout Team Flow
            └── Agents/Scout Lead/     # Scout Lead Agent (orchestrator)
                ├── Actions/           # Scout Lead's tools
                │   ├── invoke_specialist/
                │   ├── get_project_snapshot/
                │   ├── platform_catalog/
                │   └── platform_limits/
                │
                └── Flows/             # Specialist flows
                    ├── context_story/
                    │   └── Agents/context_story/
                    ├── outcomes/
                    │   └── Agents/outcomes/
                    ├── dependencies/
                    │   └── Agents/dependencies/
                    └── ... (more specialists)

Key insight: scout_team is a Flow in Carta's toolbox (not an Action). When Carta calls scout_team, it invokes a flow that contains the Scout Lead agent, which in turn calls specialist flows.

Triformer Characters

User-Facing Agents

Character	Role	Description
Beacon	Discovery Guide	Warm, calm, encouraging. Helps users find their first automation and captures initial project requirements
Carta	Blueprint Designer	Methodical, thorough. Designs detailed automation requirements with Scout Team
Triton	Client Captain	Strategic, account-level conversations and relationship management
Helm	Project Navigator	Focused on timelines, milestones, and delivery tracking
Sonar	Test Planner	Test strategy, risk analysis, quality assurance
Harbor	Priority Desk	Triage, intake, and prioritization flows

Internal Agents (Team Triformers)

Character	Role	Parent
Scout Lead	Research orchestrator	Carta
Context Story Scout	User story refinement	Scout Lead
Outcomes Scout	Metrics & success criteria	Scout Lead
Dependencies Scout	External systems & APIs	Scout Lead
Safety Scout	Risk & guardrails	Scout Lead
Guidelines Scout	Constraints & preferences	Scout Lead
README Scout	Documentation generation	Scout Lead
API Validation Scout	Live API testing	Scout Lead
Consistency Scout	Cross-section validation	Scout Lead

Building Components

Agent Files

Every agent folder contains these files:

File	Required	Description
`prompts.json`	✓	System prompt and personality
`settings.json`	✓	Model and generation settings
`io.json`	✓	Input/output schema
`nodes.json`		Tools (actions & flows) available to agent
`readme.md`		Documentation (shown in platform UI)
`requirements.json`		Component requirements spec
`.triform.json`	Auto	Platform sync tracking (don't edit)

prompts.json

{
  "system": [
    {
      "type": "template",
      "value": "You are **{{name}}**, a helpful assistant.\n\nContext: {{{inputs.context}}}",
      "enabled": true
    }
  ],
  "user": [
    {
      "type": "template",
      "value": "",
      "enabled": false
    }
  ]
}

Template Variables (Handlebars):

{{{inputs.session_id}}} - Current chat session ID
{{{inputs.callback_base_url}}} - AG-UI Bridge callback URL
{{{inputs.context}}} - User context (page visited, profile)
{{{inputs.messages}}} - Conversation history

settings.json

{
  "model": "qwen3-235b-a22b-instruct-2507",
  "settings": {
    "temperature": 0.2,
    "topP": 0.95,
    "maxTokens": 32768
  }
}

io.json

{
  "inputs": {
    "context": {
      "schema": { "type": "string" },
      "description": "User context from the chat UI"
    },
    "messages": {
      "schema": { "type": "array" },
      "description": "Conversation history"
    },
    "session_id": {
      "schema": { "type": "string" },
      "description": "Chat session identifier"
    },
    "callback_base_url": {
      "schema": { "type": "string" },
      "description": "AG-UI Bridge URL for callbacks"
    }
  },
  "outputs": {
    "result": {
      "schema": { "type": "object" },
      "description": "Agent output"
    }
  }
}

nodes.json (Agent Tools)

{
  "ask_user": {
    "component_id": "f570477b-a94e-47bf-8750-e96389c016d2",
    "inputs": {},
    "order": 1
  },
  "emote": {
    "component_id": "dec012f0-cf66-491e-af64-b8bd3c8b7bce",
    "inputs": {},
    "order": 2
  },
  "scout_team": {
    "component_id": "60a6ef91-c38d-4b3c-84c2-f8838acba747",
    "inputs": {},
    "order": 3
  }
}

Note: Tools can be Actions (Python code) or Flows (sub-agents).

Action Files

Actions are Python tools that agents can call.

File	Required	Description
`{name}.py`	✓	Python implementation
`io.json`	✓	Input/output schema
`readme.md`		Documentation
`requirements.json`		Action requirements spec
`pip_requirements.txt`		Python dependencies
`.triform.json`	Auto	Platform sync tracking

Python Action Template

"""
MyAction - Description of what this action does

QUICK REFERENCE FOR LLMs:
=========================
Basic usage:
    {"param1": "value1"}
"""

import json
import ssl
import urllib.request
from typing import TypedDict

_ssl_ctx = ssl.create_default_context()
_ssl_ctx.check_hostname = False
_ssl_ctx.verify_mode = ssl.CERT_NONE


class Inputs(TypedDict, total=False):
    """Input parameters."""
    param1: str                  # Required: Description
    session_id: str              # From agent - chat session
    callback_base_url: str       # From agent - AG-UI Bridge URL


class Output(TypedDict):
    result: dict


@triform.entrypoint
def entrypoint(inputs: Inputs) -> Output:
    """Main entry point."""
    param1 = inputs.get("param1", "")
    session_id = inputs.get("session_id", "")
    base_url = inputs.get("callback_base_url", "").rstrip("/")
    
    # Normalize AG-UI Bridge URL
    if base_url.endswith("/callback"):
        base_url = base_url.rsplit("/callback", 1)[0]
    if not base_url.endswith("/api"):
        base_url = base_url.rsplit("/api", 1)[0] + "/api" if "/api" in base_url else base_url + "/api"
    
    # Your logic here...
    
    return Output(result={"success": True, "data": param1})

Flow Files

Flows orchestrate multiple components (agents, actions, other flows).

File	Required	Description
`io.json`	✓	Flow inputs/outputs
`nodes.json`	✓	Components in the flow
`io_nodes.json`		Visual node positions
`readme.md`		Documentation
`requirements.json`		Flow requirements spec

nodes.json (Flow Nodes)

{
  "scout_lead": {
    "component_id": "08b33fa5-a976-42e2-9e68-7225d8c96da8",
    "inputs": {
      "mode": {"source": "parent", "target": "mode"},
      "goal": {"source": "parent", "target": "goal"}
    },
    "position": {"x": 200, "y": 100}
  }
}

Core Actions Reference

ask_user

Interactive input - ask questions or render rich components.

# Text question
{"question": "What's your company name?"}

# Component input
{
    "component": {
        "type": "single-select",
        "label": "What area interests you?",
        "options": [
            {"value": "sales", "label": "Sales"},
            {"value": "support", "label": "Support"}
        ]
    }
}

# With character expression
{
    "question": "Hello! What brings you here?",
    "character": {
        "character_id": "beacon",
        "expression": "friendly_greeting"
    }
}

Component Types:

Selection: single-select, multi-select, button-group, dropdown
Ratings: slider, star-rating, emoji-rating, nps, likert
Date/Time: date, time, datetime, date-range
Confirmation: confirm, approval, consent, danger-confirm
Text: text, textarea, number
Complex: tags, key-value, orderable-list, table, file

emote

Express emotional states to make conversations feel alive.

# Basic expression
{"expression": "happy_success"}

# With feeling and reason (shown under avatar)
{
    "expression": "think_processing",
    "feeling": "Focused",
    "reason": "Analyzing your requirements"
}

# Different character
{"character_id": "carta", "expression": "explain_answer"}

Expressions:

Category	Expressions
Positive	`friendly_greeting`, `happy_success`, `celebrate_big`
Neutral	`neutral_default`, `listen_curious`, `explain_answer`, `calm_info`
Working	`think_processing`
Negative	`confused_question`, `warn_caution`, `error_sad`
Idle	`sleep_idle`

set_progress

Update progress indicator.

{
    "process_name": "Understanding Your Needs",
    "progress": 25
}

submit_project (Beacon)

Complete discovery and create project.

{
    "project_name": "Lead Qualification",
    "project_description": "Automatically qualify leads",
    "user_name": "John Doe",
    "user_email": "john@acme.com"
}

project_edit (Carta)

Edit project requirements.

{
    "operation": "add_requirement",
    "category": "userStories",
    "item": {
        "id": "US-01",
        "role": "Finance assistant",
        "goal": "Have invoice matched automatically"
    }
}

web_search

Search, scrape, or crawl the web.

{
    "query": "How do Pipedrive webhooks work?",
    "mode": "search"  # or "scrape", "crawl"
}

Writing Agent Prompts

Structure

Role Definition - Who is the agent
Core Mission - What they accomplish
Personality - Character traits
Voice & Tone - Communication style
Tools Reference - How to use actions
Conversation Flow - Interaction pattern
Output Format - What to produce

Template

### Triformer {Name} – Character Guide

**Role:**
You are **Triformer {Name}**, the **{Title}** for Triform.

**Core Mission**
{What this agent helps users accomplish}

---

### Personality
- {Trait 1} – {description}
- {Trait 2} – {description}

---

### Voice & Tone
- Use clear, simple language
- Ask one focused question at a time
- Regularly reflect back what you heard

---

### Tools

#### 1. ask_user
{Usage instructions with examples}

#### 2. emote
{Usage instructions}

---

### Conversation Flow
1. {Step 1}
2. {Step 2}
3. {Step 3}

---

### Final Output
{What the agent produces when done}

Triggers

endpoints.json

Configure API endpoints:

{
  "nodes": {
    "beacon": {
      "component_id": "uuid-of-beacon-agent",
      "method": "POST",
      "payload_mapping": {
        "context": "$.context",
        "messages": "$.messages",
        "session_id": "$.session_id"
      }
    }
  },
  "enabled": true,
  "ingress_tokens": ["token-uuid"]
}

chat.json

Enable chat interface:

{
  "enabled": true
}

Integration with AG-UI Bridge

Triformer agents communicate with users through the AG-UI Bridge:

User → Chat UI → AG-UI Bridge → Triform Platform → Your Agent
                      ↑                                 ↓
                      └────────── Callbacks ────────────┘
                         (ask_user, emote, set_progress)

Required inputs (automatically injected):

session_id - Chat session identifier
callback_base_url - AG-UI Bridge URL

Best Practices

Agents

Use ask_user for all user communication
Use emote to make interactions feel alive
Use set_progress to keep users informed
Delegate complex analysis to sub-flows

Actions

Validate all required parameters
Return structured error responses
Document thoroughly for LLMs
Handle network timeouts

Prompts

Give concrete examples
Define clear boundaries
Include tool documentation
Model the conversation flow

Development Workflow

# Pull project
triform projects pull <project-id>
cd Triformers

# Start auto-sync
triform projects watch

# Create new agent (with watch running)
mkdir "Flows/MyFlow/Agents/MyAgent"
# → Platform creates agent with default files
# → Files are pulled to your folder

# Edit files in your IDE
# → Changes sync automatically

# Test
triform execute <component-id> --trace

# Deploy
triform projects deploy

License

Proprietary - Triform AI

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.triform		.triform
Agents/Beacon		Agents/Beacon
Flows		Flows
Triform/_s organization/Triformers		Triform/_s organization/Triformers
triggers		triggers
.gitattributes		.gitattributes
LICENSE		LICENSE
readme.md		readme.md
requirements.json		requirements.json
triformers.env		triformers.env

License

TriformAI/Triformers

Folders and files

Latest commit

History

Repository files navigation

Triformers

Quick Start

Architecture

Core Principle: Agents in Flows

Directory Structure

Nesting Example: Carta with Scout Team

Triformer Characters

User-Facing Agents

Internal Agents (Team Triformers)

Building Components

Agent Files

prompts.json

settings.json

io.json

nodes.json (Agent Tools)

Action Files

Python Action Template

Flow Files

nodes.json (Flow Nodes)

Core Actions Reference

ask_user

emote

set_progress

submit_project (Beacon)

project_edit (Carta)

web_search

Writing Agent Prompts

Structure

Template

Triggers

endpoints.json

chat.json

Integration with AG-UI Bridge

Best Practices

Agents

Actions

Prompts

Development Workflow

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages