Extending Flow
An app can ship its own tools, agents, triggers and skills for Flow. You write them in Python and register them in hooks.py, and Flow adds them to the site on the next bench migrate.
Add a tool
A tool is a Python function an agent can call. The model reads the function's docstring and type hints to decide when to call it.
# my_app/ai.py
import frappe
from frappe.flow import ToolContext, tool
@tool
def get_open_todos(allocated_to: str, *, ctx: ToolContext) -> list[dict]:
"""List open ToDo items for a user."""
return frappe.get_list("ToDo", filters={"allocated_to": allocated_to, "status": "Open"})
# hooks.py
flow_tools = ["my_app.ai.get_open_todos"]
The tool runs with the permissions of the person chatting, so use calls that check permissions, such as frappe.get_list.
| Option | When to use it |
|---|---|
@tool(requires_confirmation=True) |
The tool changes data. Flow asks the user to approve each call. |
@tool(background=True) |
The tool is slow. Flow runs each call as a background job. |
Add an agent
# my_app/ai.py
from frappe.flow import Agent
todo_assistant = Agent(
name="Todo Assistant",
model="Claude Sonnet 4.6", # the name of a Flow Model on the site
instructions="You help users manage their ToDos.",
tools=[get_open_todos],
)
def agents():
return [todo_assistant]
# hooks.py
flow_agents = ["my_app.ai.agents"]
After a migrate, users can pick the agent in a chat. A System Manager can disable it or change its model, but the rest is read-only.
Run an agent from code
run = todo_assistant.run(
"List open ToDo items assigned to me",
on_complete="my_app.ai.save_result",
)
run returns right away. When the agent finishes, Flow calls the on_complete function with the run.
Add a trigger
# my_app/ai.py
from frappe.flow import Trigger
def triggers():
return [
Trigger(
title="Plan urgent ToDos",
agent="Todo Assistant",
doctype="ToDo",
doc_event="after_insert",
condition='doc.priority == "High"',
prompt="Read ToDo {{ doc.name }} and email its owner a short plan.",
run_as="todo-bot@example.com",
)
]
# hooks.py
flow_triggers = ["my_app.ai.triggers"]
For a schedule, pass cron instead of doctype and doc_event. Set run_as to a user with only the roles the trigger needs.
Add a skill
Create skills/<name>/SKILL.md in the root of your app, and the built-in agent picks it up.
---
name: close-todos
description: Close overdue ToDos.
---
Close each open ToDo dated before today.