# Bucket agent

Ask natural-language questions about files in a bucket. Returns an answer plus file cards.

## Enable

Turn on intelligence for the bucket and enable the **agent** feature.

## API

```bash
curl -s -X POST \
  -H "Authorization: Bearer $FR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"sunset drone clips from italy"}' \
  https://www.file.rocks/api/v1/workspaces/$WS/buckets/$BUCKET/agent
```

Requires scope `agent:run`. REST: [Agent API](/docs/api/agent).

## MCP

Tool `ask_agent` with `bucketId` + `query`.

## Session (in-app)

`POST /api/workspace/{workspaceId}/bucket/{bucketId}/agent` with the same JSON body (cookie session + dogfood allowlist).

## How it works

Combines keyword search on keys/descriptions with pgvector semantic search over enriched embeddings, then asks a Replicate LLM to summarize matches. No web tools — bucket scope only.