Skip to main content
This document covers export_to_sftp (display name “SFTP Upload”), the agent tool that delivers a platform file to a folder on a connected SFTP server. For automated inbound folder polling, see SFTP File Import Trigger.

​
Authentication and enablement

The tool uses a workspace SFTP credential integration (integrations.service_name = 'sftp'). The hidden integration_id is resolved from the configured tool binding with first_active; credentials are loaded in the worker only after verifying that the integration belongs to the task workspace and is active. Both password and PEM private-key authentication are supported. Every export requires the host-key fingerprint captured during connection validation, so the tool does not silently fall back to an unverified SSH host. Off by default — enable it in the agent’s Tools panel. It is billed at the same per-call rate as the OneDrive and SharePoint export tools.

​
Inputs

Required:
  • file_url: URL of the source file in platform storage, or from a tool such as generate_file, python_code, or another file-producing tool.
  • file_name: Destination filename including its extension, for example invoice-1722000000.edi. It must be a single filename, not a path.
Optional:
  • folder_path: Folder beneath the integration’s configured base_path, for example qa/reports. Missing folders are created automatically. Omitted means the configured base path.
  • conflict_behavior:
    • replace (default): converge on one destination path. An existing file is atomically replaced using the OpenSSH POSIX rename extension.
    • rename: preserve the existing file and choose name (1).ext, name (2).ext, and so on.
    • fail: return an error without changing the existing file.
Absolute paths, .. traversal, sibling-prefix escapes, separators in file_name, and NUL bytes are rejected before upload.

​
Upload mechanics

  1. Download the complete source through the platform file-storage service.
  2. Resolve the destination beneath the connection’s absolute base_path.
  3. Write a unique hidden temporary sibling such as .report.csv.part-<uuid>.
  4. Close the complete temporary file.
  5. Rename it into the final destination.
  6. Stat the final file and verify its byte count.
Temporary files are removed on handled failures. A worker or server crash can leave an orphaned .part-* file, but it cannot expose a partial file under the requested final name. Replacing an existing file requires server support for posix-rename@openssh.com; the tool returns an error instead of falling back to non-atomic remove-then-rename behavior. New files and rename deliveries use standard SFTP rename.

​
Size and retry behavior

The maximum source size is 500 MB, matching platform file storage. The current implementation downloads and uploads the content from worker memory. The default replace behavior is retry-friendly: repeating the same call converges on the same path and content. rename intentionally creates another uniquely named file on a retry. If exactly-once delivery matters, use a deterministic filename with replace, or make the receiving system idempotent.

​
Output

The structured result contains:
  • tool_name
  • the final file_name (including any conflict suffix)
  • requested folder_path
  • file_size
  • applied conflict_behavior
  • completed_at
SFTP does not provide a public file URL, so the tool returns destination metadata rather than a link.

​
Auditing and errors

Connect, stat, create-folder, put, rename, and cleanup operations emit host-only external_call audit events under ProviderSftp. Audit events do not include remote paths, file names, credentials, or file contents. Common failures include:
  • missing or expired source file_url
  • invalid destination path or filename
  • inactive or cross-workspace integration
  • missing or changed host-key fingerprint
  • authentication or remote folder permission failure
  • same-name collision with conflict_behavior: "fail"
  • SFTP server without POSIX rename support when replacing an existing file
  • final remote size not matching the source byte count