Multi-chat in-app agent and bucket ask API·View as Markdown

Library agent

Ask natural-language questions about files, run library tools, and keep chat history. The in-app agent is a Linear-style multi-chat panel; the v1 REST agent endpoint remains search-only.

Enable

Turn on intelligence for the bucket and enable the agent feature. In-app access is dogfood-gated.

In-app (session)

Bottom-right Agent + History bar:

Multiple conversations with auto-named titles
Minimize to a pill / close (history kept)
Compact bucket control, @ file/folder/person mentions, page context, image attachments
Save as page on search result strips (creates a Your Pages document with a live query block)
Tool-calling loop with status lines, confirm cards for destructive actions, and streamed final answers
Page tools: get_page, create_page, update_page, add_page_block, update_page_block, delete_page_block, list_pages, run_page, delete_page, get_bucket_usage
Page-authoring asks enter a page builder harness (plan → mutate → verify → fix, up to 12 steps) that matches page purpose to blocks
Block types include query, graph, custom note, Custom UI (allowlisted components + named NL queries), media, and page embeds
create_page queryText must be a short library search; full user requests are not used as search queries

Session APIs under /api/workspace/{workspaceId}/agent/:

Route	Role
`GET/POST conversations`	List / create
`GET/PATCH/DELETE conversations/{id}`	Load, rename, `uiState`, delete
`POST conversations/{id}/messages`	SSE turn (status, tool, confirm, token, files, done)
`GET mentions?bucketId=&q=`	Recent or search files/folders/people
`POST attachments`	Upload image into `_agent/{conversationId}/`

Legacy session shortcut (search-only):

POST /api/workspace/{workspaceId}/bucket/{bucketId}/agent with { "query": "…" }.

API (v1)

curl -s -X POST \
  -H "Authorization: Bearer $FR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"find photos of sunsets"}' \
  https://www.file.rocks/api/v1/workspaces/$WS/buckets/$BUCKET/agent

Requires scope agent:run. REST: Agent API. This path is search + summary only (no tool loop).

MCP

Tool ask_agent with bucketId + query. Hygiene tools (trash_files, move_files, automations, suggestions) are available to API agents via MCP; the in-app panel uses the same shared services.

How the in-app loop works

Plan tool calls with Sonnet (JSON; override FILE_ROCKS_AGENT_MODEL).
Emit short status lines while tools run.
Pause on destructive tools until the user confirms.
Stream the final natural-language answer token-by-token.
Persist messages; auto-name the chat after the first exchange.

Library tools include search/list, get_file, and get_files_metadata (descriptions, tags, sizes). Follow-up turns reuse the prior file catalog so recommend/compare questions can use descriptions without re-listing.