Skip to content

feat(agent): send Alexandria exchange settings and answer approvals #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mogery merged 1 commit into from
Oct 6, 2026
Merged

feat(agent): send Alexandria exchange settings and answer approvals #305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 41 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -695,23 +695,32 @@ firecrawl agent <job-id> --wait

#### Agent Options

| Option | Description |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `--urls <urls>` | Comma-separated URLs to focus extraction on |
| `--model <model>` | `spark-2` (default). `spark-1-mini` and `spark-1-pro` are deprecated and run `spark-2` |
| `--effort <level>` | Reasoning effort: `low`, `medium`, or `high` |
| `--schema <json>` | JSON schema for structured output (inline JSON string) |
| `--schema-file <path>` | Path to JSON schema file for structured output |
| `--max-credits <number>` | Maximum credits to spend (job fails if exceeded) |
| `--webhook <url-or-json>` | Webhook URL or configuration |
| `--status` | Check status of existing agent job |
| `--cancel` | Cancel an active agent job by job ID |
| `--wait` | Wait for agent to complete before returning results |
| `--poll-interval <seconds>` | Polling interval in seconds when waiting (default: 5) |
| `--timeout <seconds>` | Timeout in seconds when waiting (default: no timeout) |
| `-o, --output <path>` | Save output to file |
| `--json` | Output as JSON format |
| `--pretty` | Pretty print JSON output |
| Option | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `--urls <urls>` | Comma-separated URLs to focus extraction on |
| `--model <model>` | `spark-2` (default). `spark-1-mini` and `spark-1-pro` are deprecated and run `spark-2` |
| `--effort <level>` | Reasoning effort: `low`, `medium`, or `high` |
| `--schema <json>` | JSON schema for structured output (inline JSON string) |
| `--schema-file <path>` | Path to JSON schema file for structured output |
| `--max-credits <number>` | Maximum credits to spend (job fails if exceeded) |
| `--webhook <url-or-json>` | Webhook URL or configuration |
| `--alexandria` | Let the agent call Alexandria providers (implied by the flags below); `--no-alexandria` keeps it off them |
| `--toolkits <slugs>` | Comma-separated provider slugs the agent may use (up to 5; default: the whole catalog) |
| `--max-calls <n>` | Most provider calls the agent may make this turn (1-30) |
| `--require-approval` | Stop for approval before any paid provider call (needs `--mode chat`) |
Comment thread
capy-ai[bot] marked this conversation as resolved.
| `--approve <approvalId>` | Approve the previous turn's pending approval (needs `--thread`) |
| `--call-ids <ids>` | With `--approve`: comma-separated call IDs to approve (default: all) |
| `--always` | With `--approve`: stop asking for the rest of the thread |
| `--decline <approvalId>` | Decline the previous turn's pending approval (needs `--thread`) |
| `--on-terms-required <action>` | When a provider needs data terms the team has not accepted: `skip` it (default) or `ask` |
| `--status` | Check status of existing agent job |
| `--cancel` | Cancel an active agent job by job ID |
| `--wait` | Wait for agent to complete before returning results |
| `--poll-interval <seconds>` | Polling interval in seconds when waiting (default: 5) |
| `--timeout <seconds>` | Timeout in seconds when waiting (default: no timeout) |
| `-o, --output <path>` | Save output to file |
| `--json` | Output as JSON format |
| `--pretty` | Pretty print JSON output |

#### Examples

Expand All @@ -735,6 +744,21 @@ firecrawl agent abc123-def456-... --json
firecrawl agent abc123-def456-... --wait --poll-interval 10
```

#### Alexandria providers

A run uses Alexandria providers only when it starts with an Alexandria flag. A follow-up turn (`--thread`) keeps the previous turn's setting for every Alexandria flag it omits.

```bash
# Let the agent use two providers
firecrawl agent "Find the head of sales at example.com" --toolkits apollo,crunchbase --wait

# Ask before any paid provider call, then answer the approval on the next turn
firecrawl agent "Find the head of sales at example.com" --mode chat --require-approval --wait
firecrawl agent "Go ahead" --thread <thread-id> --mode chat --approve <approval-id> --wait
```

A run that stops for approval prints its approval ID and the exact `--approve` / `--decline` follow-up commands. With `--json`, read `pendingApproval` and `exchange` from the output.

---

### `interact` - Interact with scraped pages
Expand Down
4 changes: 2 additions & 2 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "firecrawl-cli",
"version": "1.26.1",
"version": "1.26.2",
"publishConfig": {
"tag": "latest"
},
Expand Down Expand Up @@ -85,7 +85,7 @@
"dependencies": {
"@inquirer/prompts": "^8.2.1",
"commander": "^14.0.2",
"firecrawl": "4.40.0",
"firecrawl": "4.44.0",
"yaml": "^2.9.0",
"zod-to-json-schema": "3.24.6"
}
Expand Down
38 changes: 19 additions & 19 deletions pnpm-lock.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 10 additions & 0 deletions skills/firecrawl-agent/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,16 @@ Run `firecrawl agent --help` for the full option list.

**Done when:** the output file contains valid JSON answering the request — or a job ID was intentionally returned for later polling.

## Alexandria providers

A run uses connected Alexandria data providers only when it starts with an Alexandria flag: `--alexandria`, `--toolkits <slugs>` (up to 5), `--max-calls <n>`, `--require-approval`, or `--on-terms-required skip|ask`. Follow-ups on its thread keep those settings.

```bash
firecrawl agent "find the head of sales at <company>" --toolkits apollo,crunchbase --wait --json -o .firecrawl/contacts.json
```

With `--require-approval` (needs `--mode chat`), a run can end on a `pendingApproval` instead of making a paid call. Ask the user, then answer it on the same thread with `--thread <threadId> --mode chat --approve <approvalId>` (or `--decline <approvalId>`). A `terms` approval only continues after an organization admin has accepted the provider's terms in the Firecrawl dashboard; approving does not accept them.
Comment thread
capy-ai[bot] marked this conversation as resolved.
Comment thread
capy-ai[bot] marked this conversation as resolved.

## Job IDs

Omitting `--wait` returns a job ID. A UUID positional argument is auto-detected as a status check:
Expand Down
Loading
Loading