---
title: "Extending Flow"
space: "Framework"
url: "https://docs.frappe.io/framework/flow/extending-flow"
updated: "2026-11-18"
---

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.

```python
# 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"})
```

```python
# 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

```python
# 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]
```

```python
# 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

```python
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

```python
# 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",
		)
	]
```

```python
# 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.

```markdown
---
name: close-todos
description: Close overdue ToDos.
---

Close each open ToDo dated before today.
```