Tutorial: Organizing your code

Level 3 – Lesson 1 of 5 – Structure your Agent Studio code so it stays manageable as your project grows.

Organize Python functions into utility files, use standard imports for helpers, and use conv.functions for main functions – this keeps complex projects readable and maintainable.

This lesson assumes familiarity with Python and functions. Some examples reference flows, which are covered in the next lesson — you can follow along without understanding flows yet, or read Lesson 2 first if you prefer.

How Agent Studio organizes code

Each entry on the Tools page is a Python file, not just a single function. This means you can define multiple functions in one file – utility helpers, validation logic, formatters – alongside the main function that Agent Studio creates.

functions/
├── getOrder.py              # Main function + any helpers
├── formattingUtils.py       # Collection of utility functions
├── startOrderTrackingFlow.py
└── orderTrackingFlow/       # Flow functions (one folder per flow)
    ├── saveTrackingNumber.py
    └── trackingNumberConfirmed.py

Key rules:

• Each file has one main function with the same name as the file – this is the one Agent Studio validates and constrains (it must accept conv as the first argument)
• You can define additional functions above the main function – these are helpers that don’t need to follow Agent Studio’s signature rules
• Flow functions live in a subfolder named after the flow

Utility files

You don’t need 50 separate function entries for 50 helpers. Group related utilities in a single file:

# formattingUtils.py
import re
def get_digits_only(text: str) -> str:
    """Extract only digits from text."""
    return re.sub(r'\D', '', text)
def is_valid_tracking_number(number: str) -> bool:
    """Validate format: exactly 3 letters followed by 5 digits."""
    return bool(re.match(r'^[A-Za-z]{3}\d{5}$', number.strip()))
def tracking_number_to_words(number: str) -> str:
    """Convert tracking number to TTS-friendly format."""
    letters = number[:3]
    digits = number[3:]
    digit_words = {
        '0': 'zero', '1': 'one', '2': 'two', '3': 'three',
        '4': 'four', '5': 'five', '6': 'six', '7': 'seven',
        '8': 'eight', '9': 'nine'
    }
    letter_part = ' '.join(letters.upper())
    first_two = ' '.join(digit_words[d] for d in digits[:2])
    last_three = ' '.join(digit_words[d] for d in digits[2:])
    return f"{letter_part} - {first_two} - {last_three}"
# Main function (required by Agent Studio, but not LLM-callable)
def formatting_utils(conv):
    pass

The main function at the bottom is required by Agent Studio but can be a no-op. Set the LLM description to indicate this file is a utility collection, not an LLM-callable function.

Importing functions

There are two ways to use code from other files.

Method 1: Python imports

Standard Python import syntax works for any function in any file:

# Import a specific utility
from functions.formattingUtils import is_valid_tracking_number
# Import a main function from another file
from functions.getOrder import getOrder
# Import a flow function
from functions.orderTrackingFlow.trackingNumberConfirmed import tracking_number_confirmed

When using Python imports with main functions, you must pass conv (and flow for flow functions) as arguments:

order = getOrder(conv, tracking_number)

Method 2: conv.functions and flow.functions

The platform-supported method for calling main functions:

# Call a global function
order = conv.functions.getOrder(tracking_number)
# Call a flow function
flow.functions.trackingNumberConfirmed()

Advantages:

• Autocomplete and type hints in the editor
• No need to pass conv or flow – they’re handled automatically
• Officially supported by the platform

Limitation: You can only reference main functions this way. You cannot access utility helpers (like is_valid_tracking_number) through conv.functions.

Check your understanding

When to use which method

Practical example: order tracking

Here’s how a real flow function uses both import methods:

from functions.formattingUtils import is_valid_tracking_number
def save_tracking_number(conv, flow, tracking_number: str) -> str:
    # Use imported utility for validation
    if not is_valid_tracking_number(tracking_number):
        return "That doesn't look right. The tracking number should be 3 letters followed by 5 digits. Ask the user to try again."
    # Use conv.functions for the main getOrder function
    order = conv.functions.getOrder(tracking_number)
    if order is None:
        return f"No order found for {tracking_number}. Ask the user to double-check."
    conv.state["order"] = order
    conv.state["tracking_number"] = tracking_number
    flow.goto_step("report_status")
    return f"Order found: {order}"

Function types and their roles

As your project grows, distinguishing between different function types becomes critical. Here’s a reference for how to think about each type:

Separation of concerns

Follow a “thin flows, fat services” approach:

• Keep LLM-facing flow functions focused on: collecting user input, writing state, and transitioning steps
• Put deterministic logic (validation, comparisons, branching rules, API formatting) in helper modules
• Do not import LLM-facing functions into unrelated helpers as a way to reuse business logic – reuse helper functions instead

Best practices

Common pitfalls

Try it yourself

from functions.trackingUtils import is_valid_tracking_number
from functions.trackingUtils import tracking_number_to_words
def save_tracking_number(conv, flow, tracking_number: str) -> str:
    if not is_valid_tracking_number(tracking_number):
        return "Invalid format. Ask the user to try again."
    order = conv.functions.getOrder(tracking_number)
    if order is None:
        return "Order not found."
    readable = tracking_number_to_words(tracking_number)
    conv.state["order"] = order
    flow.goto_step("confirm")
    return f"Found order for {readable}: {order}"

Check your understanding