Manual Coding (Python)

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.

1. Getting Started

2. Building Assistants

3. Graph Studio (Workflow Builder)

4. DevStudio (Tool Builder)

5. Triggers & Intents

6. Builds & Environments

7. Observability & Billing

8. User Management

9. Reference

10. Troubleshooting & Support

Tool Structure

Parameters

inputs

env_variables

Return Format

output

captured_variables

Example Tool

Best Practices

Keep Business Logic Separate

Handle Errors Gracefully

Return Structured Data

Capture Reusable Values

Use Environment Variables for Secrets

Common Use Cases

Testing

​Tool Structure

​Parameters

​inputs

​env_variables

​Return Format

​output

​captured_variables

​Example Tool

​Best Practices

​Keep Business Logic Separate

​Handle Errors Gracefully

​Return Structured Data

​Capture Reusable Values

​Use Environment Variables for Secrets

​Common Use Cases

​Testing

Tool Structure

Parameters

inputs

env_variables

Return Format

output

captured_variables

Example Tool

Best Practices

Keep Business Logic Separate

Handle Errors Gracefully

Return Structured Data

Capture Reusable Values

Use Environment Variables for Secrets

Common Use Cases

Testing