Skip to content
Nappai Documentation

Python Code Structured

Python Code Structured turns a Python function you write into a tool. You write the code, choose which function runs, and the component creates the fields to fill in from its arguments. You can give that function to an agent, which uses it when needed and fills in the arguments itself, or run it as one more step of the flow with the values you write.

The code runs separately from the flow and with a time limit, so a program that never finishes does not block the rest.

When to use it

  • You need an agent to perform a business calculation that must always come out the same, such as a rate, a discount or a delivery time.
  • You want to give an agent your own validation rule, for example checking the format of an internal code.
  • You need to transform a text or some data with logic no other component covers.

Configuration

FieldWhat it does
Tool Code (required)The Python code with one or more functions. If you state each argument’s type (str, int, float, bool, list, dict), the agent knows what kind of value to send. Arguments can have default values.
Tool Function (required)The function in the code that runs. The list is filled with the functions in Tool Code; press the refresh button if you have just changed the code.
Tool Name (required)The name the agent sees for the tool, for example calculate_shipping.
Description (required)What the agent reads to know when to use it, for example “Calculates the shipping cost from the weight in kilos and the destination country”.
argument: Description (required)One field appears for each argument of the chosen function. If you use the component as a tool, write here the explanation the agent will read to fill in that argument. If you use the Text output, write here the argument’s value.
Parent document vectorstoreOptional input. This version of the component does not use it; you can leave it empty.

Advanced options

FieldWhat it does
Return DirectlyIf you turn it on, the agent hands the function’s result to the user as it is, without writing its own answer. Off by default.
Classes and FunctionsFilled in automatically from Tool Code. You don’t need to touch them.

Output

There are two outputs; connecting one hides the other.

  • Tool: the function ready for an agent. Connect it to the agent’s Tools input. The agent receives what the function returns as text.
  • Text: runs the function with the values written in each argument’s field and delivers what it returns as a message.

In both cases, anything the function writes with print also appears in the result.

Example

A courier company wants its assistant to work out the price of a shipment with its rate.

  1. In Tool Code, write: 
    def calculate_shipping(weight_kg: float, country: str):
        base = 5 if country.lower() == "spain" else 12
        return f"{base + weight_kg * 1.5:.2f} euros"
  2. In Tool Function, pick calculate_shipping.
  3. Put calculate_shipping in Tool Name and “Calculates the price of a shipment from the weight in kilos and the destination country” in Description.
  4. In weight_kg: Description write “Package weight in kilos” and in country: Description, “Destination country”.
  5. Connect the Tool output to the agent’s Tools input. When a customer asks how much it costs to send 3 kilos to France, the agent uses the function and answers with the price.

Good practices

  • Write functions with a plain def and each argument’s declaration on a single line.
  • Make the function return a clear text: that is what the agent will read.
  • If the function fails, the agent receives an empty answer. Test the function with the Text output before giving it to the agent.