Tools

Reusable @tool capabilities agents can invoke.

Basic

Mathematical and date/time utilities:

Web

Web scraping and content extraction:

Help / documentation

Read the built Sphinx singlehtml manual (same source as the Help desktop app):

Read Agency Sphinx singlehtml help (TOC + semantic section search).

agency.tools.help.singlehtml_path()[source]

agency.tools.help.parse_help_sections(path)[source]

Parse singlehtml into (heading_path, body_text) sections.

agency.tools.help.read_agency_help_text(query='', max_chars=None, *, path=None, k=6)[source]

Core implementation (testable without LangChain invoke).

Database

Database query and schema tools:

class agency.tools.database.DatabaseSchemaGenerator[source]

Bases: object

Automatically generates database schema for the chatbot.

static get_field_info(field)[source]

Extract useful information from a model field.

Parameters:: field – Django model field
Returns:: Dictionary with field information
Return type:: Dict

static get_model_info(model)[source]

Extract complete information from a model.

Parameters:: model – Django model class
Returns:: Dictionary with model information
Return type:: Dict

static generate_schema(app_names=None)[source]

Generate complete schema for specified apps.

Parameters:: app_names (List[str]) – App labels to include. Default: installed domain apps (agency, chat, boe, bopv) — never the legacy system label.
Returns:: Dictionary with schema information
Return type:: Dict

static generate_tool_description(schema)[source]

Generate tool description based on schema.

Parameters:: schema (Dict) – Database schema dictionary
Returns:: Formatted tool description string
Return type:: str

class agency.tools.database.DatabaseReadTool(app_names=None, *, name='database_read', description='', args_schema=<class 'agency.tools.database.DatabaseReadTool.Arguments'>, return_direct=False, verbose=False, callbacks=None, tags=None, metadata=None, handle_tool_error=False, handle_validation_error=False, response_format='content', extras=None, db_schema=<factory>)[source]

Bases: BaseTool

Tool to read data from the local database with auto-generated schema.

name: str

__init__(app_names=None, **kwargs)[source]

Initialize the tool with auto-generated schema.

Parameters:

app_names (List[str]) – List of app names to include in schema
**kwargs – Additional arguments for BaseTool

db_schema: Dict

description: str: Used to tell the model how/when/why to use the tool.

class Arguments(*, model, user=None, query='', q_filter='', limit=10)[source]

Bases: BaseModel

Input parameters for DatabaseReadTool.

Parameters:

model (str) – Database model to query
user (int | None) – User ID if you know it (optional)
query (str) – Search query for content filtering (optional)
q_filter (str) – Django Q object filter as text (optional)
limit (int) – Maximum number of objects to return (default: 10)

model: str

user: int | None

query: str

q_filter: str

limit: int

model_config = {}

args_schema: Type[BaseModel]

Pydantic model class to validate and parse the tool’s input arguments.

Args schema should be either:

A subclass of pydantic.BaseModel.
A subclass of pydantic.v1.BaseModel if accessing v1 namespace in pydantic 2

return_direct: bool

Whether to return the tool’s output directly.

Setting this to True means that after the tool is called, the AgentExecutor will

get_model_class(model_name)[source]

Get model class by name.

Parameters:: model_name (str) – Name of the model to retrieve
Returns:: Django model class
Raises:: ValueError – If model not found or cannot be loaded

model_config = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'protected_namespaces': ()}

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

get_schema_info()[source]

Return schema information for debugging.

Returns:: Dictionary with schema information
Return type:: Dict

Agent

Agent management tools:

Human

HITL interrupt tool:

HITL tool: pause a run and ask a human via LangGraph interrupt.

ask_human publishes a debug event and returns interrupt({...}) so the run can be resumed after the human answers (see resume_mission / Interruption).

Python interpreter

Python code execution tools:

A tool for running python code in a REPL.

Taken from https://github.com/langchain-ai/langchain-experimental/blob/main/libs/experimental/langchain_experimental/utilities/python.py

agency.tools.interpreter.warn_once()[source]

Warn once about the dangers of PythonREPL.

class agency.tools.interpreter.PythonREPL(*, _globals=<factory>, _locals=<factory>)[source]

Bases: BaseModel

Simulates a standalone Python REPL.

globals: Dict | None

locals: Dict | None

static sanitize_input(query)[source]

Sanitize input to the python REPL.

Remove whitespace, backtick & python (if llm mistakes python console as terminal)

Parameters:: query (str) – The query to sanitize
Returns:: The sanitized query
Return type:: str

classmethod worker(command, globals, locals, queue)[source]

run(command, timeout=None)[source]

Run command with own globals/locals and returns anything printed.

Parameters:

command (str) – Python code to execute
timeout (int | None) – Timeout in seconds (optional)

Returns:

Output from the command execution or error message

Return type:

str

model_config = {}

agency.tools.interpreter.sanitize_input(query)[source]

Sanitize input to the python REPL.

Remove whitespace, backtick & python (if llm mistakes python console as terminal)

Parameters:: query (str) – The query to sanitize
Returns:: The sanitized query
Return type:: str

class agency.tools.interpreter.PythonREPLTool(*, name='Python_REPL', description='A Python shell. Use this to execute python commands. Input should be a valid python command. If you want to see the output of a value, you should print it out with `print(...)`.', args_schema=None, return_direct=False, verbose=False, callbacks=None, tags=None, metadata=None, handle_tool_error=False, handle_validation_error=False, response_format='content', extras=None, python_repl=<factory>, sanitize_input=True)[source]

Bases: BaseTool

Tool for running python code in a REPL.

name: str

description: str: Used to tell the model how/when/why to use the tool.

python_repl: PythonREPL

sanitize_input: bool

model_config = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'protected_namespaces': ()}

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

class agency.tools.interpreter.PythonInputs(*, query)[source]

Bases: BaseModel

Python inputs.

query: str

model_config = {}

class agency.tools.interpreter.PythonAstREPLTool(*, name='python_repl_ast', description='A Python shell. Use this to execute python commands. Input should be a valid python command. When using this tool, sometimes output is abbreviated - make sure it does not look abbreviated before using it in your answer.', args_schema=<class 'agency.tools.interpreter.PythonInputs'>, return_direct=False, verbose=False, callbacks=None, tags=None, metadata=None, handle_tool_error=False, handle_validation_error=False, response_format='content', extras=None, globals=<factory>, locals=<factory>, sanitize_input=True)[source]

Bases: BaseTool

Tool for running python code in a REPL.

name: str

description: str: Used to tell the model how/when/why to use the tool.

globals: Dict | None

locals: Dict | None

sanitize_input: bool

args_schema: Type[BaseModel]

Pydantic model class to validate and parse the tool’s input arguments.

Args schema should be either:

A subclass of pydantic.BaseModel.
A subclass of pydantic.v1.BaseModel if accessing v1 namespace in pydantic 2

classmethod validate_python_version(values)[source]

Validate that Python version is 3.9 or higher.

Parameters:: values (Dict) – Model values to validate
Returns:: Validated values
Raises:: ValueError – If Python version is too old
Return type:: Any

model_config = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'protected_namespaces': ()}

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Icons

Local ComfyUI (Compose comfy, SD 1.5) draws pixels on the GPU. Ollama x/flux2-klein / x/z-image-turbo when the runtime supports image gen; otherwise OpenAI Images or fal FLUX. The bitmap is keyed to a 128×128 white-on-transparent dock glyph. Optional tool_id is the catalog id (tools.agent.create_agent) or a unique leaf (create_agent); a miss still saves the PNG and lists closest rows. Each catalog leaf maps to a concrete pictogram (clock, calculator) so SD 1.5 is not asked to draw Spanish abstractions. The tool result echoes pictogram, SD prompt, negative and checkpoint. list_catalog_tools (secretary) finds tools without an icon.

Generate Agency-style tool icons via an image model (not JSON geometry).

Ollama image models when the runtime supports them; otherwise OpenAI Images or fal FLUX. The bitmap is keyed to a 128×128 white-on-transparent dock glyph.

Pictures

generate_image is the color picture tool (256–1024, default 768). Local ComfyUI first; pin model=fal-ai/flux-lora (or fal-ai/flux/schnell) when FAL_KEY is set. Saves to Photos. Call show_media with the photo id so the operator Media player shows it. Optional display assigns the kiosk. Do not use the icon tool for maps or posters.

edit_image changes existing Photos rows (or whatever is on Media). One picture: FAL FLUX /image-to-image first; ComfyUI LoadImage + denoise if FAL is down. Default strength 0.35. Source aspect is kept (long side ≤ 1024). Two or more photo_ids: FLUX Kontext multi (fal-ai/flux-pro/kontext/max/multi) with data-URI image_urls. Needs FAL_KEY; no Comfy fallback. Result is a new generated photo on Media.

Generate and edit color pictures (ComfyUI / FAL FLUX).

Secretary

High-level operator tools bound to the secretary runtime (user_id, agent_id, thread_id). They never take ambient admin. Desktop chrome uses Agency Bus: open_window / close_window publish desktop.<address>.visibility.changed; show_media publishes desktop.media.now_playing.changed and opens the Media singleton. See Veronica — built-in secretary.

High-level secretary tools for Veronica (context-bound, no ambient admin).

Display

Kiosk operator tools. An agent inspects screens/views/scopes, publishes a View, assigns it to one named display, and mutates Scope properties (the live slide). Never fan-out to every kiosk. Protected (padlock) screens and views refuse agent writes. show_image_on_display is the presentation shortcut (Media image + image_url) for a single named screen. Compose templates with <agency-include namespace="display.example.clock">. Resolve by name, slug, or namespace — never Channels group names.

High-level agency.display tools for agents (Veronica and specialists).

Do not send Channels group names. Resolve displays/views/scopes by id, slug, namespace, or unique name. Scope is the property bus — set_display_property changes the live slide.