General code tools

General code tools let you extend Enterprise h2oGPTe agents with custom Python code. You upload a Python script (or ZIP package), write a system prompt that tells the agent how to call it, and the agent runs your code during conversations.

Use general code tools when you need agents to:

• Apply company-specific business logic (brand guidelines, pricing rules, compliance checks)
• Generate custom file formats (presentations, reports, spreadsheets)
• Connect to internal APIs or databases
• Run data transformations unique to your organization
• Automate repetitive workflows that require custom code

Prerequisites

• Access to Enterprise h2oGPTe with the ConfigureAgents permission
• A Python script (.py) or ZIP package (.zip) containing your tool code
• Familiarity with your tool's function names, parameters, and expected output

How general code tools work

When you start an agent chat, Enterprise h2oGPTe loads your tool code into the execution environment. Your system prompt tells the agent what the tool does and how to call it. During the conversation, the agent writes and runs a Python code block that imports your tool and calls its functions.

The execution flow:

1. You upload a Python file, then write a system prompt describing the tool.
2. Enterprise h2oGPTe adds the system prompt to the agent's context at the start of each session.
3. When the agent determines your tool is relevant, it writes a Python code block that imports and calls your tool.
4. Enterprise h2oGPTe runs the code and returns the output to the agent.
5. The agent reads the output and uses it to respond to the user.

Single file vs. ZIP package:

If your tool fits in one script with no local imports, upload it as a single .py file. This works for most tools.

If your tool has multiple files (for example, a main script that imports helper modules, configuration files, or data assets), package everything into a .zip archive and select Unzip file on server during upload. Enterprise h2oGPTe extracts the contents and preserves the module structure. Make sure the import paths in your code match the directory layout inside the ZIP.

Use case (Branded presentations for an enterprise)

In an enterprise, the team of analysts, product managers, and executives uses Enterprise h2oGPTe daily to summarize reports, compare quarterly performance, and create materials for customers. Every presentation that leaves the organization must follow strict brand guidelines including specific accent colors, a corporate font, and a standard slide layout. Employees typically spend time manually reformatting each presentation deck.

To solve this, the platform team builds a general code tool called generate_presentation. When a user asks for a presentation, the agent extracts the relevant content, calls the tool, and outputs a polished .pptx file with the organization's brand colors, fonts, and layout applied. They upload the tool, write a system prompt that tells the agent to use it whenever a user asks for a presentation or slide deck, and select Enable by Default so it is active for every agent session across the organization. From that point on, any employee who asks the agent to "create a deck comparing Q3 and Q4 results" or "build a summary presentation from this uploaded report" receives a download-ready, brand-compliant PowerPoint file. There is no need for manual formatting, and once created, the tool can be accessed from any chat within any collection.

This guide walks through that exact workflow. Replace the brand colors, fonts, and layout constants in the example code with your own organization's brand kit.

Prepare your tool code

Before you begin, write a Python script that contains the function you want the agent to call. The name you give this function is the name you set as the Tool name when you upload it.

Example: Branded PowerPoint generator

import argparse
import json
from pptx import Presentation
from pptx.util import Inches, Pt, Emu
from pptx.dml.color import RGBColor
from pptx.enum.text import PP_ALIGN
from pptx.enum.shapes import MSO_SHAPE

# Replace these colors with your organization's brand kit
BRAND_NAVY = RGBColor(0x00, 0x30, 0x57)
BRAND_CORAL = RGBColor(0xFF, 0x6F, 0x61)
DARK_TEXT = RGBColor(0x1A, 0x1A, 0x2E)
LIGHT_TEXT = RGBColor(0x4A, 0x4A, 0x68)
WHITE = RGBColor(0xFF, 0xFF, 0xFF)
LIGHT_BG = RGBColor(0xF0, 0xF4, 0xF8)
FONT_NAME = "Calibri"
SLIDE_WIDTH = Inches(13.333)
SLIDE_HEIGHT = Inches(7.5)


def _add_bar(slide, top, height, color=BRAND_NAVY):
    bar = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, Emu(0), top, SLIDE_WIDTH, height)
    bar.fill.solid()
    bar.fill.fore_color.rgb = color
    bar.line.fill.background()


def _add_text(slide, left, top, width, height, text, size, color,
              bold=False, align=PP_ALIGN.LEFT):
    box = slide.shapes.add_textbox(left, top, width, height)
    box.text_frame.word_wrap = True
    run = box.text_frame.paragraphs[0].add_run()
    run.text = text
    run.font.name = FONT_NAME
    run.font.size = Pt(size)
    run.font.color.rgb = color
    run.font.bold = bold
    box.text_frame.paragraphs[0].alignment = align
    return box


def _build_title_slide(prs, title, subtitle=""):
    slide = prs.slides.add_slide(prs.slide_layouts[6])
    slide.background.fill.solid()
    slide.background.fill.fore_color.rgb = WHITE
    _add_bar(slide, Inches(0), Inches(0.15), BRAND_NAVY)
    _add_text(slide, Inches(0.8), Inches(2.0), Inches(11.5), Inches(2.0),
              title, 40, BRAND_NAVY, bold=True)
    if subtitle:
        _add_text(slide, Inches(0.8), Inches(4.0), Inches(11.5), Inches(1.0),
                  subtitle, 20, LIGHT_TEXT)
    _add_bar(slide, Inches(7.0), Inches(0.5), BRAND_CORAL)


def _build_content_slide(prs, title, content):
    slide = prs.slides.add_slide(prs.slide_layouts[6])
    slide.background.fill.solid()
    slide.background.fill.fore_color.rgb = WHITE
    _add_bar(slide, Inches(0), Inches(0.08), BRAND_NAVY)

    header = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE, Emu(0), Inches(0.08), SLIDE_WIDTH, Inches(1.2)
    )
    header.fill.solid()
    header.fill.fore_color.rgb = LIGHT_BG
    header.line.fill.background()

    _add_text(slide, Inches(0.8), Inches(0.25), Inches(11.5), Inches(0.9),
              title, 28, BRAND_NAVY, bold=True)

    body = slide.shapes.add_textbox(
        Inches(0.8), Inches(1.6), Inches(11.5), Inches(5.2)
    )
    tf = body.text_frame
    tf.word_wrap = True

    lines = content.split("\n") if "\n" in content else [content]
    for i, line in enumerate(lines):
        stripped = line.strip()
        if not stripped:
            continue
        is_bullet = stripped.startswith(("- ", "* "))
        text = stripped.lstrip("-* ").strip() if is_bullet else stripped

        p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
        run = p.add_run()
        run.text = ("  •  " + text) if is_bullet else text
        run.font.name = FONT_NAME
        run.font.size = Pt(18)
        run.font.color.rgb = LIGHT_TEXT if is_bullet else DARK_TEXT
        p.space_after = Pt(10)


def generate_presentation(title, slides_json, subtitle=""):
    """Generate a branded PowerPoint presentation.

    Args:
        title: Presentation title for the first slide.
        slides_json: JSON string with slide content.
            Format: [{"title": "Slide Title", "content": "Slide body text"}, ...]
            Content supports newlines and bullet points (lines starting with - or *).
        subtitle: Optional subtitle for the title slide.

    Returns:
        Path to the generated .pptx file.
    """
    prs = Presentation()
    prs.slide_width = SLIDE_WIDTH
    prs.slide_height = SLIDE_HEIGHT

    _build_title_slide(prs, title, subtitle)

    slides = json.loads(slides_json)
    for slide_data in slides:
        _build_content_slide(prs, slide_data["title"], slide_data["content"])

    output_path = f"{title.replace(' ', '_').replace('/', '_')}.pptx"
    prs.save(output_path)
    return output_path


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("title")
    parser.add_argument("slides_json")
    parser.add_argument("--subtitle", default="")
    args = parser.parse_args()
    result = generate_presentation(args.title, args.slides_json, args.subtitle)
    print(f"Presentation saved to: {result}")

Tool code requirements:

• Use .py for single-file tools or .zip for multi-file packages
• The tool name must match the primary function name (for example, generate_presentation)
• Maximum file size: 100 MB
• If using a .zip file, select Unzip file on server during upload

Save your code as a .py file to upload in the next step.

Step 1: Open the general code tool dialog

To access the tool creation form:

1. In the Enterprise h2oGPTe navigation menu, click Agents.

2. Click the Tools tab.

3. Click + New Tool and select General Code Tools.

This opens the Upload General Code Tool dialog where you configure and upload your tool.

Step 2: Upload the tool

In the Upload General Code Tool dialog, fill in the following fields:

1. Enter a Tool name that matches your primary function name (for example, generate_presentation).

2. Enter a Description that summarizes what the tool does.

3. Upload your Python file: click the upload area and select your .py or .zip file.

4. Write a System prompt that tells the agent how to use the tool (see Step 3).

5. If uploading a .zip file, select the Unzip file on server checkbox.

6. To make this tool available in all new agent sessions, select the Enable by Default checkbox.

7. Click Add Tool.

Step 3: Write the system prompt

The system prompt tells the agent when to use your tool, what it does, and how to call it. Enterprise h2oGPTe adds this text directly into the agent's context at runtime, so the instructions must be specific and complete.

Write the system prompt as if it is the only documentation the agent will ever see about your tool.

What to include

At minimum, a system prompt should cover:

• When to use it and when not to (compared to the built-in Python tool)
• Function signature: name, arguments with types and allowed values, return value, and any files the tool creates
• Required environment variables (if any), so the user knows which keys to assign to the tool
• A complete code example that the agent can copy and adapt, including the three required header comments (# execution: true, # filename:, # tool:)

Wrap the prompt in XML tags

Wrap the entire system prompt in XML tags named after your tool (for example, <generate_presentation>...</generate_presentation>). The XML tags create a clear boundary between your tool's instructions and those of other tools in the agent's context. Without them, the agent may mix up instructions when multiple tools are active.

Example system prompt for the PowerPoint generator

The following example shows a complete system prompt for the generate_presentation tool. Copy the entire block into the System prompt field:

<generate_presentation>
NAME: generate_presentation
PURPOSE: Generate branded PowerPoint presentations with corporate styling
(navy #003057 / coral #FF6F61 color scheme, Calibri font, standard slide layout).

WHEN TO USE
- Use `generate_presentation` when the user asks for a presentation, slide deck, or PowerPoint file
- Do NOT use the built-in `python` tool to create PowerPoint files — only `generate_presentation` applies the correct brand styling and has access to the uploaded tool code
- Convert the user's requested content into well-structured slides with clear titles and bullet points

API
generate_presentation(title, slides_json, subtitle="") -> str
Returns the file path to the generated .pptx file (e.g., "Quarterly_Review.pptx").
The file is written to the current working directory.

Parameters:
  - title (str, required) — presentation title displayed on the title slide
  - slides_json (str, required) — JSON string: [{"title": "Slide Title", "content": "Body text"}].
    Content supports newlines (\n) and bullet points (lines starting with - or *)
  - subtitle (str, optional, default="") — subtitle displayed below the title on the first slide

HOW TO RUN — emit exactly this block (all three comments are required):

```python
# execution: true
# filename: create_presentation.py
# tool: generate_presentation

from generate_presentation import generate_presentation
full_path = generate_presentation(
    title="Quarterly Business Review",
    slides_json='[{"title": "Revenue Summary", "content": "- Total revenue grew 8% YoY\n- Recurring revenue: 72% of total"}, {"title": "Customer Metrics", "content": "- Net new customers: 1,200\n- Churn reduced to 2.1%"}]',
    subtitle="Q3 2025 Results"
)
print(full_path)
```
</generate_presentation>

Required header comments

Every code block in the system prompt must include three header comments. These comments tell Enterprise h2oGPTe how to run the code:

Comment	Purpose	Example
# execution: true	Marks the block for execution	# execution: true
# filename: <name>.py	Sets the script filename	# filename: create_presentation.py
# tool: <tool_name>	Runs the code in your custom tool's environment so it can access the uploaded code and assigned environment variables	# tool: generate_presentation

caution

All three header comments are required. Without # tool: generate_presentation, the code runs in the default Python environment. The default environment does not have access to your uploaded tool code or its assigned environment variables.

Step 4: Add authentication keys (optional)

If your tool needs API keys or credentials, create an authentication key and assign it to the tool. For step-by-step instructions on creating keys and assigning them, see Managing authentication keys in the Agent tool configuration guide.

Step 5: Test the tool

To verify the tool works as expected, test it in an agent chat session.

1. Go to a collection and start a new chat session.

2. Click the Agent button on the chat box and select an agent type (for example, General).

3. Click Customize to open the Customize chat side dialog. Go to Configuration, scroll down to the Custom Tool section, and confirm your tool is listed and enabled.

4. Send a test message to the agent.

Example test messages for the PowerPoint generator:

• "Create a presentation summarizing the key findings from the documents in this collection. Include one slide per major topic."
• "Build a five-slide deck with an executive summary, three detail slides covering the main themes, and a next-steps slide."
• "Generate a PowerPoint from this uploaded report. Use bullet points to highlight the important data points on each slide."

After the agent responds, check the Steps section in the agent response to confirm the tool ran correctly:

1. Expand the Steps panel to see the agent's execution trace.
2. Verify the agent wrote a code block that imports and calls your tool.
3. Confirm the tool executed without errors.
4. Check that the .pptx file is available for download in the agent response.
5. Download the file and verify it uses your configured brand colors and fonts.

note

The following is a sample presentation generated using the steps from this guide: Deploy_a_Custom_Agent_with_a_Local_MCP_Tool.pptx.

tip

If the agent does not use your tool, review the system prompt. Make sure it clearly describes when to use the tool and includes a complete code example.

Next steps

• Follow Tutorial 9: Creating and using a custom agent tool for a hands-on walkthrough with the brand colors example
• Learn about MCP servers for tools with structured input/output schemas
• Review the REST API reference for SDK and cURL examples for the custom tools API
• Explore the Agent tool configuration guide for built-in tool setup

---

Feedback

• Submit and view feedback for this page
• Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai