Skip to main content
Manual Coding provides maximum flexibility and is ideal when built-in tools are insufficient or custom logic is required.

​
Tool Structure

Every Python tool in Dev Studio follows a standard execution pattern with a single entrypoint: 
def main(inputs, env_variables):

​
Parameters

​
inputs

A dictionary containing values from session variable (user_variables, capture_variables) Example: 
{
    "urgency": "routine",
    "appointment_type": "telehealth"
}

​
env_variables

A dictionary containing environment variables, secrets, API keys, and configuration values. Example: 
{
    "API_TOKEN": "...",
    "DATABASE_URL": "..."
}

​
Return Format

The script must return a dictionary with the following structure: 
return {
    "output": output_dict,
    "captured_variables": captured_variables
}

​
output

The output object is returned directly to the agent and can be:
  • Displayed to users
  • Used in prompts
  • Passed to downstream workflow steps
  • Consumed by other agents
Example: 
{
    "appointments": [...]
}

​
captured_variables

Values inside captured_variables are automatically stored as session variables and become available throughout the workflow. Example: 
{
    "slots_count": 3,
    "doctor_names": [
        "Dr. Sarah Mitchell",
        "Dr. Emily Watson"
    ]
}
These variables can be referenced by subsequent agents, tools, and workflow steps during the active session.

​
Example Tool

The following example generates appointment slots based on user preferences: 
def main(inputs, env_variables):

    try:

        appointments = generate_slots(inputs)

        output_dict = {
            "appointments": appointments
        }

        captured_variables = {
            "slots_count": len(appointments)
        }

    except Exception as e:

        output_dict = {
            "error": str(e)
        }

        captured_variables = {}

    return {
        "output": output_dict,
        "captured_variables": captured_variables
    }

​
Best Practices

​
Keep Business Logic Separate

Move complex logic into helper functions rather than placing everything inside main(). 
def fetch_customer(customer_id):
    ...

def main(inputs, env_variables):
    customer = fetch_customer(
        inputs["customer_id"]
    )

​
Handle Errors Gracefully

Always wrap execution in a try/except block and return meaningful error messages. 
try:
    ...
except Exception as e:
    output_dict = {
        "error": str(e)
    }

​
Return Structured Data

Prefer dictionaries and arrays over plain text so downstream agents can reliably consume the output. 
{
    "customer": {
        "id": 123,
        "name": "John Smith"
    }
}

​
Capture Reusable Values

Store frequently reused values in captured_variables. 
captured_variables = {
    "customer_id": customer["id"],
    "customer_name": customer["name"]
}

​
Use Environment Variables for Secrets

Never hardcode API keys, credentials, or secrets in your code. 
api_key = env_variables.get(
    "API_TOKEN"
)

​
Common Use Cases

  • Calling external APIs
  • Database queries
  • Data transformation
  • Custom business rules
  • File processing
  • SSH and Running commands
  • Validation and enrichment pipelines

​
Testing

See Testing Tools.