Files and cloud storage

An agent can transfer an attachment to a connected app or save a private cloud copy. These destinations have different lifetimes.

Transfer a local file to an app

Ask the agent to upload the attachment to a specific connected app and location. The agent finds the action with sokko_find_actions or sokko_app_actions. It computes the file size and MD5 in its local terminal, then calls sokko_stage_file with the action, filename, MIME type, size, and MD5.

The tool returns an upload URL and a file descriptor. The agent uploads the original bytes with an HTTP PUT and the returned headers. After the upload succeeds, it supplies the descriptor to the app action. For an already-staged file, the tool returns status: staged and the agent can use the descriptor without another PUT.

The upload step only stages the file. It does not create the destination file. The agent must run the destination action and verify the result and folder. It must not use a local path or an R2 key as the descriptor's s3key.

Connected apps must be enabled, with a paid plan, credits, and an active account for the action. If several accounts are connected, select the intended account. File staging accepts files up to 100 MiB. Each provider can impose a lower limit.

Composio manages deletion of its staging objects after 24 hours. Signed URL expiry and object deletion are separate. This policy does not delete a copy in Drive, an email attachment, or an execution log. See Composio's retention policy.

Save a private cloud copy

Ask the agent to save the file in Sokko cloud storage. The agent calculates its size and SHA-256, calls sokko_cloud_file_upload, and uploads the bytes using the returned URL and headers. It then calls sokko_cloud_file_commit. The platform verifies the size and checksum before making the file available.

Use sokko_cloud_files to list files, sokko_cloud_file_download to obtain a five-minute download link, and sokko_cloud_file_delete to delete a file. Anyone with a download link can use it while it is valid. Agents can access only their own cloud files. Workspace members with file access can manage workspace files through the API.

Cloud storage must be configured by the platform operator. The default workspace allowance is 1 GiB, shared across agents. Each file can be up to 100 MiB. Pending uploads reserve space. Upload URLs expire after 15 minutes. Cleanup removes uncommitted uploads after expiry and removes files marked for deletion after any upload URL has expired. Files marked for deletion cannot receive new download links. Existing download links can remain usable until physical deletion.

Cloud storage is optional. A request to transfer a file to a connected app does not also save a persistent cloud copy. Ask for that copy separately.

If a chat attachment has already expired from the agent's local storage, send it again. A transfer cannot recover a source file that no longer exists.