Agent Tools Reference

Reference for tools available to the interactive Dagu agent in the Web UI.

Provider-native web search is configured in Personality & Web Search and model requests; it is not exposed as a separate callable tool. Workflow agent steps also add a step-only output tool and omit navigate, ask_user, and delegate.

bash

Execute shell commands.

Parameter	Type	Required	Default	Description
command	string	Yes		Shell command to execute
timeout	integer	No	120	Timeout in seconds (max: 600)

Output: Combined stdout/stderr, truncated at 100,000 characters.

Policy Behavior:

• Bash execution is controlled by the configured regex-based bash policy.
• By default, bash is allowed unless a deny rule matches.
• In interactive sessions, deny rules with ask_user prompt for approval when safe mode is on.
• With safe mode off, ask_user rules run without prompting. block rules still fail.
• Backticks, $(), heredocs, and process substitution are denied before execution.

---

read

Read file contents with line numbers.

Parameter	Type	Required	Default	Description
path	string	Yes		File path (absolute or relative to working directory)
offset	integer	No	1	Starting line number (1-based)
limit	integer	No	2000	Maximum lines to read

Limits:

• Maximum file size: 1MB
• Directories cannot be read (use bash with ls)

Output Format:

     1	first line
     2	second line
...
... [123 more lines, use offset=2001 to continue]

---

patch

Create, edit, or delete files.

Parameter	Type	Required	Description
path	string	Yes	File path
operation	string	Yes	One of: create, replace, delete
content	string	For create	Full file content
old_string	string	For replace	Exact text to find (must be unique in file)
new_string	string	For replace	Replacement text

Create Operation:

• Creates parent directories automatically
• Directory permissions: 0750
• File permissions: 0600

Replace Operation:

• old_string must appear exactly once in the file
• Whitespace and indentation must match exactly

DAG Validation: Files ending in .yaml within the DAGs directory are validated automatically after modification using spec.LoadYAML.

---

think

Record reasoning without executing actions.

Parameter	Type	Required	Description
thought	string	Yes	Reasoning or planning text

Output: "Thought recorded. Continue with your plan."

---

navigate

Navigate the user to a UI page.

Parameter	Type	Required	Description
path	string	Yes	Target path

Common Paths:

• /dags - DAG list
• /dags/<name> - DAG details
• /dags/<name>/spec - DAG specification tab
• /dags/<name>/history - History tab
• /dag-runs - All DAG runs
• /dag-runs/<name>/<run-id> - Specific run details
• /queues - Queue management
• /docs - Documents page
• /docs/<doc-id> - Specific document

Admin-only Pages:

• /users
• /api-keys
• /terminal
• /git-sync
• /agent-settings

---

ask_user

Prompt the user with a question.

Parameter	Type	Required	Default	Description
question	string	Yes		Question text
options	string[]	No		Predefined choices (2-4 items)
allow_free_text	boolean	No	false	Enable text input field
free_text_placeholder	string	No		Placeholder for text input
multi_select	boolean	No	false	Allow selecting multiple options

Constraints:

• If options is provided, it must contain 2-4 items

---

delegate

Spawn sub-agents that execute tasks in parallel.

Parameter	Type	Required	Description
tasks	array	Yes	List of sub-task objects (max: 8)
tasks[].task	string	Yes	Description of the sub-task for the sub-agent

Each sub-agent:

• Runs in a separate session linked to the parent via ParentSessionID
• Receives the same system prompt and all tools except delegate, ask_user, navigate, remote_agent, and list_contexts
• Does not receive the parent conversation history
• Executes its full tool-calling loop, then returns its last assistant text response as a summary to the parent

Sub-agents inherit the tool policy configured in agent settings. In safe mode, bash commands denied with ask_user behavior are also denied because the approval prompt cannot be delivered to the user.

Concurrency: All tasks run in parallel. If more than 8 tasks are provided, only the first 8 execute; the rest are dropped with a notice appended to the output.

Output Format:

The tool returns numbered summaries, one per sub-agent:

[1] Analyze database config: The config at /etc/app/db.yaml uses...

[2] Check disk usage: /var/log is at 78% capacity...

If tasks were truncated:

(2 additional tasks truncated — max 8 per call)

Task descriptions in the output are truncated to 60 characters.

Availability: Interactive chat only. Not available in DAG agent steps (type: agent). Calling delegate in a DAG agent step returns "Delegate capability is not available in this context".

Sub-sessions: Each delegated agent gets its own chat session so you can inspect its work separately when needed. The tool result includes delegate_ids for follow-up automation.

SSE streaming: Sub-agent messages are forwarded through the parent session's SSE stream as delegate_messages events. The parent also receives delegate_event notifications with type started or completed for each sub-agent. The frontend renders a floating panel per active sub-agent.

Cost: Sub-agent LLM costs are rolled up to the parent session's total cost.

Example:

{
  "tasks": [
    {
      "task": "Read the file /opt/app/docker-compose.yaml and check if the postgres service has a health check configured"
    },
    {
      "task": "Run 'df -h' and report any filesystems above 80% usage"
    },
    {
      "task": "Read /opt/app/config/cron.yaml and verify all cron expressions are valid"
    }
  ]
}

---

remote_agent

Send a task through a configured remote CLI context.

Parameter	Type	Required	Description
context	string	Yes	Remote CLI context name
message	string	Yes	Task or prompt to send to the remote agent

Availability: Only shown when remote contexts are configured.

Behavior:

• Requires execute permission
• Creates a remote session and polls until completion
• Remote execution always runs in safe mode
• Returns the remote agent's final result, truncated if necessary

---

list_contexts

List remote CLI contexts available to remote_agent.

Parameter	Type	Required	Description
name_filter	string	No	Optional substring filter for context names

Availability: Only shown when remote contexts are configured.

Behavior:

• Requires execute permission

Output: A markdown list of matching context names and descriptions.