Tools
Give agents capabilities beyond text generation. Tools let agents search, store, delegate, and interact with external services.
Overview#
Tools are declared in agent.yaml. The agent decides when to use them based on the conversation context and its goals.
| Category | Tools | Use Case |
|---|---|---|
| Web | web_search, web_fetch | Research, live data |
| Browser | browser_tools (12 tools) | Web automation with the user's logged-in browser |
| Files | artifacts | Reports, exports, downloads |
| Storage | sqlite | Preferences, tracking, queryable history |
| Delegation | delegate, report_to_parent | Multi-agent orchestration |
| Notes | journal, recall | Internal notes, session context |
| HTTP | Custom http_tools | OAuth APIs (Gmail, Stripe, etc.) |
| Bash | Custom bash_tools | CLI commands (trivy, ffmpeg) |
| Audio | tts, audio_mixer | Voice, meditations, podcasts |
| UI | render_* | Interactive components |
Declare the tools your agent needs in the tools list. Some tools accept additional configuration:
tools:
- name: web_search
- name: web_fetch
- name: artifacts
- name: delegate
config:
max_depth: 2
- name: sqlite
config:
tables:
history:
columns:
id: { type: integer, primary_key: true }
query: { type: string, required: true }HTTP Tools#
HTTP tools let agents interact with OAuth-based APIs like Gmail, Twitter, Stripe, and Shopify. Standard tools are generic — HTTP tools let agents interact with the user's own accounts through authenticated API calls.
Each HTTP tool defines an endpoint, method, authentication, and parameter schema:
http_tools:
twitter_post_tweet:
description: "Post a tweet to Twitter/X"
endpoint: "/api/v1/twitter/tweets"
method: POST
auth: bearer
twitter_token: true
params:
text:
type: string
description: "The tweet text (max 280 chars)"
required: true
body_template: '{
"text": "{{text}}"
{{if reply_to}}, "reply_to": "{{reply_to}}"{{end}}
}'| Field | Description |
|---|---|
description | What the tool does. Shown to the LLM for tool selection. |
endpoint | API path to call. Relative to the proxy base URL. |
method | HTTP method: GET, POST, PUT, DELETE, PATCH. |
auth | Authentication type. Usually bearer. |
{service}_token | Flags which OAuth token to inject (e.g. twitter_token, gmail_token). |
params | Parameter schema. Each param has type, description, and required. |
body_template | Go-style template for the request body. Uses {{param}} placeholders. |
response_format | Optional. How to parse the response before returning to the LLM. |
OAuth Configuration
Use the {service}_token field to specify which OAuth token the tool requires. The runtime injects the user's token automatically:
# Twitter/X
twitter_token: true
# Gmail / Google Calendar
gmail_token: true
# Stripe
stripe_token: trueTemplate Variables
The body_template field uses Go template syntax. Reference parameters with {{param_name}} and use conditionals with {{if field}}...{{end}}:
body_template: '{
"text": "{{text}}"
{{if reply_to}}, "reply_to": "{{reply_to}}"{{end}}
{{if media_ids}}, "media_ids": {{media_ids}}{{end}}
}'Available Integrations
| Service | Token Field | Example Endpoints |
|---|---|---|
| Twitter/X | twitter_token | Post tweets, read timeline, send DMs |
| Gmail | gmail_token | Send emails, search inbox, read threads |
| Google Calendar | gmail_token | Create events, list upcoming, check availability |
| Stripe | stripe_token | List charges, create invoices, manage subscriptions |
| Shopify | shopify_token | Manage products, orders, inventory |
linkedin_token | Post updates, manage connections |
When a user runs the agent, Rush checks if the user has the required service connected. If not, it prompts for OAuth before running.
Bash Tools#
Bash tools let agents run scoped CLI commands — security scans, media conversion, data processing. Each bash tool wraps a single command. The LLM provides arguments, not the binary name.
bash_tools:
trivy_scan:
description: "Scan for CVE vulnerabilities"
command: trivy
help_command: "trivy --help"
labels:
running: "Scanning for vulnerabilities"
finished: "Scan complete"| Shell Tool | Bash Tools | |
|---|---|---|
| Security | LLM can choose any command | Fixed command prefix — LLM only provides arguments |
| Debugging | Generic shell invocations | Named tools with structured labels |
| Help Context | LLM guesses flags and syntax | Help text injected from help_command |
| Schema | Generic string input | Specific to the command |
Dependencies
If your bash tool needs an external binary (ffmpeg, trivy, imagemagick, etc.), declare it in dependencies. At install time Rush runs the check command; if it fails, the user is shown the platform-specific install line before the agent runs.
dependencies:
- name: ffmpeg
check: "ffmpeg -version"
install:
darwin: "brew install ffmpeg"
linux: "apt-get install -y ffmpeg"
- name: trivy
check: "trivy --version"
install:
darwin: "brew install aquasecurity/trivy/trivy"
linux: "curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin"check can be any command that exits zero when the dependency is present. install.darwin and install.linux are surfaced as copy-paste snippets — Rush never runs them for you.
Audio Tools#
Audio tools enable text-to-speech and audio composition. tts converts text to spoken audio, and audio_mixer composes multiple audio segments into a single output.
Use cases include guided meditations, podcast generation, voiceovers, and narrated reports.
tools:
- name: tts
- name: audio_mixerQuick Reference#
| I need to... | Tool | Notes |
|---|---|---|
| Search the web | web_search | General research |
| Read a webpage | web_fetch | Full page content |
| Save a file | artifacts | Reports, exports |
| Query structured data | sqlite | Tables, tracking |
| Delegate to another agent | delegate | Multi-agent |
| Call an external API | http_tools | OAuth integrations |
| Run a CLI command | bash_tools | Scoped execution |
| Generate speech | tts | Voice output |
| Mix audio | audio_mixer | Composition |
| Show UI component | render_* | Interactive cards |