> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building with Triton

> Create Projects, Agents, Flows, and Actions through conversation

## Overview

Once you've defined your Project description (and possibly requirements), Triton can build it for you. This guide covers how to effectively use Triton to generate components, connect them, and get a working system.

## Building Actions

Actions are Python functions that do specific tasks.

### Basic Action creation

**You:** *"Create an Action that fetches data from a REST API"*

**Triton generates:**

* `Action.py` with:
  * Function signature
  * Type hints
  * Error handling
  * Documentation
* Input/output schema
* `requirements.txt` with dependencies

**Example output:**

```python theme={null}
import requests
from typing import Dict, Any
import logging

logger = logging.getLogger(__name__)

def fetch_data(url: str, headers: Dict[str, str] = None) -> Dict[str, Any]:
    """
    Fetches data from a REST API endpoint.
    
    Args:
        url: The API endpoint URL
        headers: Optional HTTP headers
        
    Returns:
        JSON response as dictionary
        
    Raises:
        requests.exceptions.RequestException: If the request fails
    """
    try:
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        logger.error(f"Timeout fetching {url}")
        raise
    except requests.exceptions.RequestException as e:
        logger.error(f"Error fetching {url}: {e}")
        raise
```

### Action with specific requirements

**You:** *"Create an Action that validates email addresses using a regex and checks against our blocklist in Project Variables"*

**Triton:**

* Generates regex pattern
* Adds Global Variable reference
* Includes validation logic
* Tests it

### Action with API integration

**You:** *"Create an Action that integrates with the Stripe API"*

**Triton:**

* Uses the **Knowledge Store** to research API documentation and best practices
* Generates proper API authentication code
* Creates comprehensive testing flows
* Handles errors and edge cases
* Caches API research for future reference

The Knowledge Store system enables Triton to:

* Research external APIs intelligently
* Store and retrieve API integration patterns
* Generate better code with real-world API understanding
* Test API integrations comprehensively

### Action with OAuth integration

**You:** *"Create an Action that sends emails via Gmail"*

**Triton:**

1. Generates the action code with OAuth token access
2. Uses `get_oauth_token('google')` for authentication
3. Implements Gmail API calls with proper error handling
4. Prompts you to configure OAuth modifier for Google

**Generated code includes:**

```python theme={null}
from triform import get_oauth_token
import requests

def send_gmail(to: str, subject: str, body: str) -> dict:
    """Send email via Gmail API using OAuth"""
    token = get_oauth_token('google')
    
    # Gmail API implementation
    response = requests.post(
        'https://gmail.googleapis.com/gmail/v1/users/me/messages/send',
        headers={'Authorization': f'Bearer {token.access_token}'},
        json={...}
    )
    return response.json()
```

**Triton automatically:**

* Knows which OAuth providers are available (Google, Slack, GitHub, etc.)
* Generates proper token access patterns
* Handles token refresh transparently
* Includes error handling for OAuth failures
* Prompts you to configure the OAuth modifier before execution

### Data transformation Action

**You:** *"Create an Action that takes a list of user objects and returns just their email addresses"*

**Triton generates:**

```python theme={null}
from typing import List, Dict

def extract_emails(users: List[Dict]) -> List[str]:
    """
    Extracts email addresses from a list of user objects.
    
    Args:
        users: List of user dictionaries with 'email' key
        
    Returns:
        List of email addresses
    """
    emails = []
    for user in users:
        if 'email' in user and user['email']:
            emails.append(user['email'])
    return emails
```

### Action with loops

**You:** *"Create an Action that processes a batch of orders with retry logic"*

**Triton generates:**

* Action with **for loop** to iterate over orders
* **While loop** for retry logic with exponential backoff
* Proper loop state management
* Error handling for individual items

Actions now support full loop constructs (for/while) for batch processing and iterative operations.

## Building Agents

Agents are LLM-powered components with prompts and tools.

### Simple Agent

**You:** *"Create an Agent that summarizes text"*

**Triton creates:**

* System prompt:
  ```
  You are a summarization expert. Given text input, create a concise
  summary that captures the key points. Keep summaries under 200 words.
  Use clear, professional language.
  ```
* Input schema: `{ "text": "string" }`
* Output schema: `{ "summary": "string" }`
* Model: GPT-4 (default)

### Agent with tools

**You:** *"Create an Agent that answers questions about our product catalog using a search Action"*

**Triton:**

1. First checks if `search_catalog` Action exists
2. If not, asks: *"Should I create the search\_catalog Action first?"*
3. Creates the Action
4. Creates the Agent with:
   * System prompt mentioning available tools
   * Tools configuration including `search_catalog`
   * Examples of tool usage

**System prompt:**

```
You are a product expert helping customers find information about our catalog.

Available tools:
- search_catalog: Search products by keyword, category, or ID

When a customer asks about products:
1. Use search_catalog to find relevant products
2. Present the information clearly
3. Suggest related products if appropriate

Always be helpful and accurate. If you can't find something, say so clearly.
```

### Decision-making Agent

**You:** *"Create an Agent that triages support tickets into urgent/normal/low priority"*

**Triton creates:**

* Detailed system prompt with triage criteria
* Input schema: `{ "ticket": { "subject": "string", "body": "string", "user_tier": "string" } }`
* Output schema: `{ "priority": "enum", "reason": "string", "suggested_assignment": "string" }`
* Lower temperature (0.3) for consistent decisions

## Building Flows

Flows connect components into workflows.

### Linear Flow

**You:** *"Create a Flow that validates input, processes it, and returns results"*

**Triton creates:**

```
Input → validate_input → process_data → format_output → Output
```

Each node is properly connected with appropriate data mappings.

### Parallel processing Flow

**You:** *"Create a Flow that fetches data from 3 different sources simultaneously, then combines the results"*

**Triton creates:**

```
Input → fetch_source_1 ↘
      → fetch_source_2 → combine_results → Output
      → fetch_source_3 ↗
```

Includes:

* Parallel execution of fetch Actions
* Combine node that waits for all inputs
* Proper error handling if any source fails

## Building complete Projects

Combine everything into a Project.

### End-to-end example

**You:** *"Build a complete Project for processing customer feedback: collect feedback, analyze sentiment, extract themes, generate report"*

**Triton creates:**

**1. Actions:**

* `validate_feedback` — Check feedback format
* `store_feedback` — Save to database
* `generate_report` — Format results

**2. Agent:**

* `analyze_feedback` — Sentiment analysis and theme extraction

**3. Main Flow:**

```
Input (feedback list)
  → validate_feedback (for each item)
  → store_feedback (batch)
  → analyze_feedback (Agent)
  → generate_report
  → Output (formatted report)
```

**4. Project node:**

* Exposes the main Flow as the Project entry point
* Configured with input/output schemas
* Ready to deploy

### Incremental building

You don't have to build everything at once:

**You:** *"Start a new Project called 'Email Processor'"*\
**Triton:** Creates empty Project

**You:** *"Add an Action to parse email headers"*\
**Triton:** Creates `parse_headers` Action

**You:** *"Add an Agent to classify emails"*\
**Triton:** Creates `classify_email` Agent

**You:** *"Connect them in a Flow"*\
**Triton:** Creates Flow linking parse\_headers → classify\_email

**You:** *"Add error handling for malformed emails"*\
**Triton:** Adds validation Action and error routing

## Building with context

Triton understands your existing work.

### Building on existing components

**You:** *"Create a new Flow that uses my existing Actions: fetch\_data and process\_results"*

**Triton:**

* Scans your Project
* Finds both Actions
* Creates Flow with proper connections
* Uses correct input/output schemas

### Consistent naming and patterns

**You:** *"Add another Action similar to fetch\_user\_data but for products"*

**Triton:**

* Reviews `fetch_user_data` implementation
* Creates `fetch_product_data` with similar structure
* Maintains consistent error handling
* Uses same coding style

### Building variants

**You:** *"Create a version of this Agent that's more concise"*

**Triton:**

* Copies existing Agent
* Modifies system prompt for brevity
* Names it `{original_name}_concise`
* Keeps same tools and config

## Building best practices

> **Start with the core path** — Build the main workflow first, add enhancements later

> **Test as you go** — Use Execute panel to verify each component

> **Be specific about behavior** — Tell Triton exactly what you want, including edge cases

> **Let Triton suggest** — If unsure, ask "How should I structure this?"

> **Review generated code** — Always check what Triton built before deploying

## Common building patterns

### Pattern: Extract-Transform-Load (ETL)

**You:** *"Build an ETL pipeline for customer data"*

**Triton creates:**

* Extract Action (API/database/file)
* Transform Agent/Action (cleanse, normalize)
* Load Action (destination)
* Flow connecting them with error handling

### Pattern: Request-Process-Notify

**You:** *"Build a workflow that takes requests, processes them, and notifies users"*

**Triton creates:**

* Validation Action
* Processing Agent/Flow
* Notification Action (email/webhook)
* Status tracking

### Pattern: Fan-out/Fan-in

**You:** *"Process 100 items in parallel, then aggregate results"*

**Triton creates:**

* Splitter (fan-out)
* Processing Action (parallel)
* Aggregator (fan-in)
* Flow with proper concurrency

### Pattern: Retry with backoff

**You:** *"Call this API with automatic retries"*

**Triton adds:**

* Retry decorator
* Exponential backoff
* Max attempts configuration
* Logging

## Troubleshooting building

### Problem: Triton doesn't understand the request

**Solution:** Break it down

* ❌ *"Build the whole system"*
* ✅ *"First, create an Action that validates input"*

### Problem: Generated code doesn't match needs

**Solution:** Provide examples

* *"Create an Action like this: \[paste example]"*
* *"The output should look like: \[paste JSON]"*

### Problem: Components aren't connecting properly

**Solution:** Be explicit

* *"Connect the output of fetch\_data to the input of process\_data"*
* *"Map the 'results' field to 'data' in the next node"*

### Problem: Missing error handling

**Solution:** Ask for it

* *"Add try-catch to handle network failures"*
* *"What if the input is empty?"*

## Next steps

After building:

1. Test each component with Execute panel
2. Edit and refine as needed
3. Debug any issues
4. Deploy your Project

Continue exploring the Triton documentation to learn about defining Projects, editing components, and debugging.