Functions

The functions tool is the core orchestrator of MyAi. It allows you to deploy custom Python code (3.10+ environment) that serves as the "brain" of your system — orchestrating other tools, transforming data, and implementing complex business logic.

---

Why Use Custom Functions?

• Custom Logic — implement any business rule, calculation, or data transformation not natively covered by existing tools.
• Tool Orchestration — call multiple tools (api_client, sql_client, email, canvas_editor, file_processor) in a specific sequence.
• Reusable Components — publish functions as callable artifacts, acting like internal APIs for other Workflows, Dimensions, or Functions.

Note: Functions run in a sandboxed environment. They only have access to the default_api tools and the data explicitly passed to them.

---

The Function Lifecycle

1. Run (Test)

Use functions(operation="run") to execute code privately and temporarily. Returns an execution_ref for testing with other tools. Always test thoroughly before publishing.

# Test with sample inputs
result = default_api.functions(
    operation="run",
    content="def main(order_id): return f'Processing {order_id}'",
    inputs={"order_id": "XYZ123"}
)

2. Publish (Deploy)

Use functions(operation="publish") to create a permanent, versioned artifact with a defined API contract. Once published, the function is discoverable and callable by Workflows, Dimensions, and other Functions.

result = default_api.functions(
    operation="publish",
    name="process_order",
    description="Validates and routes incoming orders",
    content=my_python_code,
    parameters=[
        {"name": "order_id", "type": "string", "required": True},
        {"name": "priority", "type": "string", "required": False}
    ]
)

3. Patch (Update)

Use functions(operation="patch") for targeted line-level updates to live functions, minimizing deployment risk.

result = default_api.functions(
    operation="patch",
    function_id="my-function-id",
    changes=[
        {"start_line": 15, "end_line": 18, "new_text": "updated_logic_here"}
    ]
)

4. Archive (Disable)

Use functions(operation="archive") to temporarily remove a function from active use without deleting it. Archived functions can be restored.

---

Parameters vs. Inputs

Understanding the distinction is important:

Concept	When	Purpose
Parameters	Defined at publish time	The API contract — names, types, descriptions of expected arguments. Visible to other tools and Workflows.
Inputs	Provided at run time	The actual runtime values for testing (e.g., inputs={"customer_id": "CUST-001"}). Not part of the permanent definition.

---

Example: Multi-Tool Orchestration

This function fetches customer data from a CRM, queries an internal database, and generates a Canvas report:

def main(customer_id: str):
    # 1. Fetch from external CRM
    crm_data = default_api.api_client(
        credentials_artifact="crm-api-creds",
        method="GET",
        endpoint=f"/customers/{customer_id}"
    )

    # 2. Query internal database for order history
    orders = default_api.sql_client(
        operation="execute_sql",
        credentials="warehouse-creds",
        sql=f"SELECT * FROM orders WHERE customer_id = '{customer_id}' ORDER BY date DESC LIMIT 10"
    )

    # 3. Build a Canvas report with the combined data
    default_api.canvas_editor(
        operation="create",
        title=f"Customer Report: {customer_id}",
        components=[
            {"type": "metric_card", "content": f"json:{crm_data}"},
            {"type": "table", "content": f"exec_ref:{orders.get('ref_id')}"}
        ]
    )

    return {"status": "success", "customer": crm_data}

---

Best Practices

Security First

Always use integration_credentials for authenticating with external services. Never hardcode sensitive information directly in function code.

Orchestrate, Don't Re-implement

Whenever an existing default_api tool can perform a task, use it rather than writing custom Python to replicate the functionality (e.g., use default_api.email() instead of a custom email library).

Keep Functions Modular

Each function should do one thing well. Smaller functions are easier to test, debug, and reuse across Workflows.

Handle Errors Gracefully

Implement try-except blocks for external API and database calls. Return meaningful error messages that help with debugging.

---

Learn More

• Data & Integration Tools — The tools your functions will call most: api_client, sql_client, file_processor.
• Architecture — How Functions relate to Skills, Dimensions, and Artifacts.