Agent Tools Reference
Agents interact with the outside world through tools. Every tool is available to every template -- the agent's system prompt and procedures determine which tools it actually uses.
Authentication
All tools that call the platform API authenticate via the X-Task-Authorization header:
X-Task-Authorization: SHA-1(projectId + tokenSecret)
X-Task-Namespace: <XPRESSAI_NAMESPACE>
X-Agent-Name: <AGENT_NAME>
Content-Type: application/json
See Agent Identity for details on how token validation works.
Tool Catalog
File Operations
Source: file_tools.py
| Function | Parameters | Description |
|---|---|---|
read_file | path: str (required) | Read the contents of a file and return as string |
write_file | path: str (required), content: str (required) | Write content to a file (creates or overwrites) |
list_files | path: str (required) | List files and directories at a path |
search_files | pattern: str (required), path: str (optional) | Search for files matching a glob pattern |
mkdir | path: str (required) | Create a directory (including parents) |
delete_file | path: str (required) | Delete a file |
move_file | source: str (required), destination: str (required) | Move or rename a file |
All file operations are sandboxed to /data/home/ via _safe_path(). Attempts to access paths outside this directory are rejected.
Task Management
Source: task_tools.py
| Function | Parameters | Description |
|---|---|---|
create_task | summary: str (required), details: str (optional), steps: list (optional), agent_id: int (optional) | Create a new task on the project task board |
list_tasks | status: str (optional) | List tasks with optional status filter |
update_task | task_id: int (required), status: str (optional), agent_id: int (optional), details: str (optional) | Update task status, assignee, or details |
Tasks are created via the platform API and appear on the project's task board (Kanban, list, or calendar view).
Scheduling
Source: schedule_tools.py
| Function | Description |
|---|---|
create_schedule | Create a recurring schedule (cron-based) |
list_schedules | List all schedules for the agent |
update_schedule | Modify a schedule's cron expression or payload |
delete_schedule | Remove a schedule |
Schedules use cron expressions. The platform converts 5-field Unix cron to 6-field Quartz cron automatically.
Messaging
Source: messaging_tools.py
| Function | Description |
|---|---|
send_message | Send a message to a conversation |
list_conversations | List conversations the agent participates in |
create_conversation | Create a new conversation with specified participants |
Agents use messaging to communicate with users and other agents through channels.
Document Conversion
Source: document_tools.py
| Function | Description |
|---|---|
convert_file_to_markdown | Convert a file (PDF, DOCX, PPTX, etc.) to Markdown |
convert_url_to_markdown | Fetch a URL and convert its content to Markdown |
Uses MarkItDown for conversion. Useful for ingesting external documents into the agent's context.
Document Creation
Source: document_create_tools.py
| Function | Description |
|---|---|
create_docx | Create a Word document |
create_xlsx | Create an Excel spreadsheet |
create_pptx | Create a PowerPoint presentation |
create_pdf | Create a PDF document |
Generated documents are saved to the agent's file system under /data/home/.
Google Workspace
Source: google_workspace_tools.py
| Function | Description |
|---|---|
create_google_doc | Create a new Google Doc |
read_google_doc | Read the content of a Google Doc |
update_google_doc | Update an existing Google Doc |
search_google_docs | Search for Google Docs by query |
create_google_sheet | Create a new Google Sheet |
read_google_sheet | Read data from a Google Sheet |
update_google_sheet | Update cells in a Google Sheet |
append_google_sheet_rows | Append rows to a Google Sheet |
create_google_slides | Create a new Google Slides presentation |
read_google_slides | Read the content of a Google Slides presentation |
update_google_slides | Update an existing Google Slides presentation |
Requires Google Workspace integration to be configured in project settings.
Atlassian (Jira & Confluence)
Source: atlassian_tools.py
| Function | Description |
|---|---|
search_confluence | Search Confluence pages by query |
get_confluence_page | Get the content of a Confluence page by ID |
create_confluence_page | Create a new Confluence page |
update_confluence_page | Update an existing Confluence page |
add_confluence_comment | Add a comment to a Confluence page |
search_jira_issues | Search Jira issues using JQL |
get_jira_issue | Get details of a Jira issue by key |
create_jira_issue | Create a new Jira issue |
update_jira_issue | Update fields on an existing Jira issue |
add_jira_comment | Add a comment to a Jira issue |
transition_jira_issue | Transition a Jira issue to a new status |
get_jira_transitions | Get available transitions for a Jira issue |
Requires Atlassian integration to be configured in project settings.
Email
Source: email_tools.py
| Function | Description |
|---|---|
send_email | Send an email via SendGrid |
Sends from the platform's configured sender address. Supports HTML and plain text bodies.
Web Search
Source: web_search_tools.py
| Function | Description |
|---|---|
web_search | Search the web and return results |
Returns a list of results with titles, URLs, and snippets.
Shell Execution
Source: shell_tools.py
| Function | Description |
|---|---|
execute_command | Execute a shell command with a configurable timeout |
Shell commands run inside the agent's container. Use with caution -- long-running commands may time out.
Image Generation
Source: image_tools.py
| Function | Parameters | Description |
|---|---|---|
generate_image | prompt: str (required), filename: str (optional) | Generate an image from a text prompt using an AI image generation model. The generated image is saved to the agent's file system under /data/home/. Supported output format is PNG. |
Content Publishing
Source: publish_tools.py
| Function | Parameters | Description |
|---|---|---|
publish_content | content: str (required), title: str (optional), destination: str (optional) | Publish content to a configured destination. Supported destinations depend on project integrations (e.g., blog platforms, CMS). The content can be plain text or Markdown. |
Procedures & Skills
Source: procedure_tools.py, skill_tools.py
| Function | Source | Description |
|---|---|---|
invoke_procedure | procedure_tools.py | Execute a named procedure (see Procedures Format) |
invoke_skill | skill_tools.py | Execute a named skill (see Skills Format) |
Voice
Source: voice_turn_tools.py
| Function | Description |
|---|---|
request_turn | Request a speaking turn in an active voice call |
Used during voice conversations to manage turn-taking between participants.
Platform HTTP Client
Source: platform_client.py
Not a tool itself, but the authenticated HTTP client used by all tools that call the platform API. Handles header injection (X-Task-Authorization, X-Task-Namespace, X-Agent-Name) and base URL resolution.