Writing Functions (Explained Simply)
A function is a plain Python callable that runs deterministic logic. It reads inputs, does some work, and returns a dictionary. No LLM, no side effects — just code.
If you are new, remember one sentence: A function step calls a Python function with inputs and stores the returned dict.
When To Use A Function
- Parsing, formatting, or transforming data.
- Classification rules or heuristic logic.
- Any operation that should always produce the same output for the same input.
If you need a language model, use an agent. If you need external side effects (APIs, files), use a tool.
Where Functions Live
Put function files in the functions/ directory. The runtime resolves them by qualified name.
functions/
stubs.py
formatters.py
my_functions.py
The Function Signature
Every function must accept a single inputs dict and return a plain dict:
def my_function(inputs: dict) -> dict:
# read from inputs
# do deterministic work
# return a dict
...That's it. No base class, no decorator, no registration — just a function.
Minimal Example
# functions/formatters.py
def format_markdown(inputs: dict) -> dict:
text = inputs.get("text", "")
report = f"# Report\n\n{text}\n"
return {"report": report}steps:
- id: format
type: function
function: formatters.format_markdown
inputs:
text: steps.summarize.summaryWhat Happens At Runtime
- The runtime reads the workflow step.
- It resolves
formatters.format_markdown→functions/formatters.py→format_markdown(). - It builds the input dict from the step's
inputs:mapping. - It calls
format_markdown(inputs). - The returned dict is stored at
steps.formatin state. Downstream steps reference its keys directly — e.g.steps.format.report.
Naming Convention
Reference functions as <module>.<function_name>:
| Reference | File | Function |
|---|---|---|
stubs.generate_summary |
functions/stubs.py |
generate_summary() |
formatters.format_markdown |
functions/formatters.py |
format_markdown() |
my_functions.classify |
functions/my_functions.py |
classify() |
More Examples
Classification heuristic:
# functions/stubs.py
def classify_severity(inputs: dict) -> dict:
issue = inputs.get("issue", "").lower()
if "crash" in issue or "down" in issue:
return {"severity": "critical", "reason": "keyword match"}
return {"severity": "low", "reason": "no critical keywords"}steps:
- id: classify
type: function
function: stubs.classify_severity
inputs:
issue: inputs.issueMulti-step pipeline with functions:
steps:
- id: summarize
type: agent
agent: summarizer
inputs:
issue: inputs.issue
- id: classify
type: function
function: stubs.classify_severity
inputs:
issue: inputs.issue
- id: format
type: function
function: formatters.format_markdown
inputs:
text: steps.summarize.summaryTesting Functions
Because functions are pure Python with no framework dependency, they're trivial to unit test:
from functions.stubs import classify_severity
def test_critical():
result = classify_severity({"issue": "server crash in prod"})
assert result["severity"] == "critical"
def test_low():
result = classify_severity({"issue": "button color is off"})
assert result["severity"] == "low"Common Mistakes
- Returning something other than a dict — the runtime expects a
dictand will error otherwise. - Using
functions/stubs.pyas the reference instead ofstubs.generate_summary— use module-dot-function format, not file paths. - Side effects in a function — functions should be pure. If you need to call an API or write a file, use a tool instead.
See Also
- Writing Workflows — How to use functions in a workflow.
- Writing Agents — LLM-backed reasoning steps.
- Writing Tools — External action steps.