Agent Configuration - Ivory Finance

The /v1/rag/answer/agent endpoint is fully model-agnostic and multi-tenant. Every request can include an optional config object that controls which AI provider, model, and database the agent uses — enabling completely isolated per-client agents.

{
  "query": "What was AWS revenue in Q4 2025?",
  "config": {
    "llm_provider": "anthropic",
    "llm_model": "claude-opus-4-6",
    "db_connection_string": "postgresql://user:pass@your-host:5432/your_db"
  }
}

All config fields are optional. Omit the entire config object (or any field within it) to use the server defaults (OpenAI GPT-4o + the Ivory Finance Postgres database).

LLM Providers

The agent supports two AI providers. Both power the same tool-calling loop and streaming answer generation.

OpenAI (default)
Anthropic (Claude)

OpenAI

The default provider. Uses the OpenAI Chat Completions API with function calling.

Field	Value
`llm_provider`	`"openai"`
`llm_model`	See model table below
Required key	`OPENAI_API_KEY` on the server

Available models

Model	Best for	Speed
`gpt-4o` (default)	Best accuracy, complex multi-step reasoning	~2–4s
`gpt-4o-mini`	Lower cost, simple queries	~0.5–1s
`o1`	Advanced reasoning, mathematical queries	~5–15s
`o3-mini`	Fast reasoning tasks	~2–5s

Example request

{
  "query": "What were Tesla's gross margins in the last three quarters?",
  "cik": "0001318605",
  "config": {
    "llm_provider": "openai",
    "llm_model": "gpt-4o"
  }
}

OpenAI is the default. If you omit the config field entirely, GPT-4o is used automatically.

Getting your OpenAI API key

Create an OpenAI account

Go to platform.openai.com and sign up or log in.

Navigate to API Keys

Click your profile icon → API Keys → Create new secret key.

Add billing

Go to Settings → Billing and add a payment method. Without credits the API returns 429 errors.

Provide the key

Contact support@ivory.finance with your key to have it configured for your account. The key is stored encrypted and never exposed in API responses.

Anthropic — Claude

Uses the Anthropic Messages API with tool use. Claude excels at long-context analysis and nuanced financial reasoning.

Field	Value
`llm_provider`	`"anthropic"`
`llm_model`	See model table below
Required key	`ANTHROPIC_API_KEY` on the server

Available models

Model	Best for	Context window
`claude-opus-4-6`	Highest accuracy, complex analysis	200K tokens
`claude-sonnet-4-6` (recommended)	Balanced speed and accuracy	200K tokens
`claude-haiku-4-5-20251001`	Fastest, simple lookups	200K tokens

Example request

{
  "query": "Summarise all material risk factors disclosed by NVIDIA in their latest 10-K",
  "cik": "0001045810",
  "config": {
    "llm_provider": "anthropic",
    "llm_model": "claude-sonnet-4-6"
  }
}

Getting your Anthropic API key

Create an Anthropic account

Go to console.anthropic.com and sign up or log in.

Navigate to API Keys

Click API Keys in the left sidebar → Create Key.

Add credits

Go to Plans & Billing → Add credits. Claude API requires a paid plan.

Provide the key

Contact support@ivory.finance with your Anthropic API key. It will be stored encrypted and tied to your Ivory Finance account.

API keys are sensitive credentials. Never include them in client-side code or public repositories. Always provision them server-side through the Ivory Finance support team. Keys are encrypted at rest using AES-256 and are never returned in API responses.

Web Search Providers

The web_search and news_search tools use a configurable search provider. Set config.search_provider to choose the engine, and supply config.search_api_key or config.search_custom_url when required.

Google (default)
Bing
DuckDuckGo
Custom API

Google

The default provider. No API key required from the caller — Google Search is available out of the box.

Field	Value
`search_provider`	`"google"` (default)
`search_api_key`	Not required

Sub-engines available

The Google provider also supports additional data sources via the service field:

`service` value	Description
`google` (default)	Broad web results
`wikipedia`	Definitions and explanations
`arxiv`	Academic and quantitative research
`reddit`	Retail investor sentiment
`x`	Real-time social commentary
`yahoo`	Finance news and portals
`reuters`	Premium financial wire (news search)

Example request

{
  "query": "What is NVIDIA's competitive position in AI chips?",
  "config": {
    "search_provider": "google"
  }
}

Google is the default. Omitting search_provider entirely uses Google Search automatically.

Microsoft Bing

Uses the Bing Web Search API v7 for web queries and Bing News Search API v7 for news queries. Requires a Microsoft Azure Cognitive Services subscription key.

Field	Value
`search_provider`	`"bing"`
`search_api_key`	Your Azure Cognitive Services subscription key

Getting a Bing Search API key

Create an Azure account

Go to portal.azure.com and sign in or create an account.

Create a Bing Search resource

Navigate to Create a resource → search for Bing Search → select Bing Search v7 → click Create.

Copy your subscription key

In your resource, go to Keys and Endpoint and copy Key 1.

Example request

{
  "query": "Tesla Q4 2025 earnings analyst reaction",
  "config": {
    "search_provider": "bing",
    "search_api_key": "YOUR_AZURE_BING_KEY"
  }
}

The service field (e.g. "google", "reuters") is ignored when using Bing — Bing handles routing internally.

DuckDuckGo

Uses the DuckDuckGo Instant Answer API via the duckduckgo-search Python package. No API key required.

Field	Value
`search_provider`	`"duckduckgo"`
`search_api_key`	Not required

Example request

{
  "query": "What are the main risks for semiconductor companies in 2026?",
  "config": {
    "search_provider": "duckduckgo"
  }
}

DuckDuckGo does not provide a commercial API. Results are fetched via the public interface and may be rate-limited under heavy usage. For production workloads, use search1api or bing.

Custom Search Endpoint

Point the agent at your own internal search service or any third-party search aggregator (e.g. Search1API, SerpAPI, Serper, Brave Search).

Field	Value
`search_provider`	`"custom"`
`search_custom_url`	Base URL of your search service
`search_api_key`	Optional — sent as `Bearer` token in `Authorization` header

Expected contract

The agent will POST to:

{search_custom_url}/search — for web_search calls
{search_custom_url}/news — for news_search calls

Request body:

{
  "query": "AWS re:Invent 2025 announcements",
  "max_results": 5
}

Expected response:

{
  "results": [
    {
      "title": "AWS re:Invent 2025: Top announcements",
      "link": "https://example.com/article",
      "snippet": "Amazon Web Services unveiled..."
    }
  ]
}

Example — internal search service

{
  "query": "Internal research notes on NVDA supply chain",
  "config": {
    "search_provider": "custom",
    "search_custom_url": "https://search.mycompany.com",
    "search_api_key": "INTERNAL_BEARER_TOKEN"
  }
}

Example — Search1API aggregator

Search1API aggregates Google, Wikipedia, arXiv, Reddit, X, Reuters, and more behind a single endpoint. It follows the custom provider contract exactly.

{
  "query": "Tesla Q3 2025 earnings report",
  "config": {
    "search_provider": "custom",
    "search_custom_url": "https://api.search1api.com",
    "search_api_key": "YOUR_SEARCH1API_KEY"
  }
}

Database Connections

The query_database tool lets the agent run structured queries against your own database. This is useful when you have proprietary financial data — internal earnings models, client portfolios, custom metrics — that you want the agent to combine with SEC filing data. Pass your database connection string in config.db_connection_string. The database type is auto-detected from the URL scheme.

PostgreSQL
MySQL
MariaDB
MongoDB
Oracle

PostgreSQL

The most commonly used relational database. Uses the psycopg2 driver.

Connection string format

postgresql://username:password@hostname:5432/database_name

Example

{
  "query": "What were our top 5 client holdings by value last quarter?",
  "config": {
    "db_connection_string": "postgresql://analyst:s3cr3t@db.mycompany.com:5432/portfolio_db"
  }
}

The agent writes SQL like this

SELECT client_id, ticker, SUM(market_value) AS total_value
FROM holdings
WHERE quarter = '2025-Q4'
GROUP BY client_id, ticker
ORDER BY total_value DESC
LIMIT 5

Hosted PostgreSQL services

Service	Connection string format
Supabase	`postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres`
Neon	`postgresql://[user]:[pass]@[host].neon.tech:5432/[db]?sslmode=require`
AWS RDS	`postgresql://[user]:[pass]@[endpoint].rds.amazonaws.com:5432/[db]`
Google Cloud SQL	`postgresql://[user]:[pass]@[ip]:5432/[db]`
Azure Database	`postgresql://[user]@[server]:[pass]@[server].postgres.database.azure.com:5432/[db]`

Ivory Finance recommends creating a read-only database user specifically for agent queries. The agent only issues SELECT statements, but defence-in-depth matters.

CREATE USER ivory_agent WITH PASSWORD 'strong_password';
GRANT CONNECT ON DATABASE your_db TO ivory_agent;
GRANT USAGE ON SCHEMA public TO ivory_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ivory_agent;

MySQL

Uses the pymysql driver.

Connection string format

mysql://username:password@hostname:3306/database_name

Example

{
  "query": "Show me revenue by product line for Q4 2025",
  "config": {
    "db_connection_string": "mysql://analyst:s3cr3t@db.mycompany.com:3306/financials"
  }
}

The agent writes SQL like this

SELECT product_line, SUM(revenue) AS total_revenue
FROM sales_summary
WHERE quarter = 'Q4-2025'
GROUP BY product_line
ORDER BY total_revenue DESC
LIMIT 20

Hosted MySQL services

Service	Connection string format
AWS RDS MySQL	`mysql://[user]:[pass]@[endpoint].rds.amazonaws.com:3306/[db]`
PlanetScale	`mysql://[user]:[pass]@[host].connect.psdb.cloud/[db]?ssl-mode=require`
Google Cloud SQL	`mysql://[user]:[pass]@[ip]:3306/[db]`
Azure Database for MySQL	`mysql://[user]@[server]:[pass]@[server].mysql.database.azure.com:3306/[db]`

Create a read-only user for agent access:

CREATE USER 'ivory_agent'@'%' IDENTIFIED BY 'strong_password';
GRANT SELECT ON your_database.* TO 'ivory_agent'@'%';
FLUSH PRIVILEGES;

MariaDB

MySQL-compatible. Uses the pymysql driver (same protocol as MySQL).

Connection string format

mariadb://username:password@hostname:3306/database_name

Example

{
  "query": "What is the average days-to-close across all deals this year?",
  "config": {
    "db_connection_string": "mariadb://analyst:s3cr3t@mariadb.mycompany.com:3306/crm_db"
  }
}

Hosted MariaDB services

Service	Connection string format
MariaDB SkySQL	`mariadb://[user]:[pass]@[host].db.mariadb.com:3306/[db]`
AWS RDS MariaDB	`mariadb://[user]:[pass]@[endpoint].rds.amazonaws.com:3306/[db]`

MariaDB and MySQL share the same wire protocol. If your MariaDB service provides a mysql:// connection string, that also works.

MongoDB

Uses the pymongo driver. MongoDB queries use a JSON descriptor format instead of SQL — the agent generates this automatically.

Connection string format

mongodb://username:password@hostname:27017/database_name
mongodb+srv://username:password@cluster.mongodb.net/database_name

Example

{
  "query": "Find all portfolio positions where unrealised P&L exceeds $1M",
  "config": {
    "db_connection_string": "mongodb+srv://analyst:s3cr3t@cluster0.abc123.mongodb.net/portfolio"
  }
}

The agent generates MongoDB queries like this

{
  "collection": "positions",
  "filter": { "unrealised_pnl": { "$gt": 1000000 } },
  "projection": { "_id": 0, "ticker": 1, "quantity": 1, "unrealised_pnl": 1 },
  "sort": { "unrealised_pnl": -1 },
  "limit": 20
}

Hosted MongoDB services

Service	Connection string format
MongoDB Atlas	`mongodb+srv://[user]:[pass]@[cluster].mongodb.net/[db]`
AWS DocumentDB	`mongodb://[user]:[pass]@[cluster].cluster-[id].[region].docdb.amazonaws.com:27017/[db]?tls=true&tlsCAFile=...`
Azure Cosmos DB	`mongodb://[account]:[key]@[account].mongo.cosmos.azure.com:10255/[db]?ssl=true`

Create a read-only MongoDB user:

db.createUser({
  user: "ivory_agent",
  pwd: "strong_password",
  roles: [{ role: "read", db: "your_database" }]
})

The agent automatically detects MongoDB from the mongodb:// or mongodb+srv:// prefix and switches from SQL to the JSON query format. You do not need to change anything in your query — just describe what you want in plain English.

Oracle Database

Uses the oracledb driver (thin mode — no Oracle Client libraries required).

Connection string format

oracle://username:password@hostname:1521/service_name

Example

{
  "query": "What is total revenue by business unit for fiscal year 2025?",
  "config": {
    "db_connection_string": "oracle://analyst:s3cr3t@oracle.mycompany.com:1521/FINPROD"
  }
}

The agent writes SQL like this

SELECT business_unit, SUM(revenue) AS total_revenue
FROM financial_summary
WHERE fiscal_year = 2025
GROUP BY business_unit
ORDER BY total_revenue DESC
FETCH FIRST 20 ROWS ONLY

Oracle uses FETCH FIRST N ROWS ONLY instead of LIMIT N. The agent is aware of this and generates correct Oracle SQL automatically.

Create a read-only Oracle user:

CREATE USER ivory_agent IDENTIFIED BY strong_password;
GRANT CREATE SESSION TO ivory_agent;
GRANT SELECT ANY TABLE TO ivory_agent;
-- Or grant per-table for tighter control:
GRANT SELECT ON your_schema.your_table TO ivory_agent;

Data Warehouses & Lakehouses

The agent supports the four most common cloud data platforms in addition to traditional databases. Pass the appropriate connection string in config.db_connection_string — the type is auto-detected from the URL scheme.

Snowflake
Databricks
Amazon Redshift
BigQuery

Snowflake

Uses the official snowflake-connector-python driver.

Connection string format

snowflake://username:password@account_identifier/database/schema?warehouse=WH_NAME&role=ROLE_NAME

URL component	Description
`account_identifier`	Your Snowflake account locator, e.g. `xy12345.us-east-1`
`database`	Snowflake database name
`schema`	Optional schema name (e.g. `PUBLIC`)
`warehouse`	Virtual warehouse to use (query param)
`role`	Optional role override (query param)

Example

{
  "query": "What were our top revenue-generating products last quarter?",
  "config": {
    "db_connection_string": "snowflake://analyst:s3cr3t@xy12345.us-east-1/FINANCE_DB/PUBLIC?warehouse=COMPUTE_WH&role=ANALYST_ROLE"
  }
}

The agent writes SQL like this

SELECT product_name, SUM(revenue) AS total_revenue
FROM FINANCE_DB.PUBLIC.sales_summary
WHERE quarter = '2025-Q4'
GROUP BY product_name
ORDER BY total_revenue DESC
LIMIT 20

Create a read-only Snowflake role for agent access:

CREATE ROLE ivory_agent;
GRANT USAGE ON WAREHOUSE compute_wh TO ROLE ivory_agent;
GRANT USAGE ON DATABASE finance_db TO ROLE ivory_agent;
GRANT USAGE ON SCHEMA finance_db.public TO ROLE ivory_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA finance_db.public TO ROLE ivory_agent;
CREATE USER ivory_agent_user PASSWORD='strong_password' DEFAULT_ROLE=ivory_agent;
GRANT ROLE ivory_agent TO USER ivory_agent_user;

Databricks SQL

Uses the databricks-sql-connector driver to connect to a Databricks SQL warehouse.

Connection string format

databricks://token:ACCESS_TOKEN@hostname/catalog?http_path=/sql/1.0/warehouses/WAREHOUSE_ID&schema=SCHEMA_NAME

URL component	Description
`ACCESS_TOKEN`	Databricks personal access token (PAT) or service principal token
`hostname`	Your Databricks workspace hostname, e.g. `adb-1234567890.0.azuredatabricks.net`
`catalog`	Unity Catalog name (e.g. `main`)
`http_path`	HTTP path of your SQL warehouse (query param)
`schema`	Optional default schema (query param)

Getting the HTTP path

In Databricks, go to SQL Warehouses → select your warehouse → Connection details → copy the HTTP path.

Example

{
  "query": "Show me daily active users by region for the last 30 days",
  "config": {
    "db_connection_string": "databricks://token:dapi123abc@adb-1234567890.0.azuredatabricks.net/main?http_path=/sql/1.0/warehouses/abc123def&schema=analytics"
  }
}

Use a service principal with CAN USE permissions on the SQL warehouse and SELECT grants on specific schemas for production workloads. Avoid using personal access tokens in shared environments.

Amazon Redshift

Redshift is PostgreSQL-wire-compatible. The agent uses psycopg2 with the redshift:// prefix.

Connection string format

redshift://username:password@cluster-endpoint:5439/database_name

Example

{
  "query": "What are total ad spend and attributed revenue for each campaign last month?",
  "config": {
    "db_connection_string": "redshift://analyst:s3cr3t@my-cluster.abc123.us-east-1.redshift.amazonaws.com:5439/analytics"
  }
}

The agent writes SQL like this

SELECT campaign_name,
       SUM(ad_spend) AS total_spend,
       SUM(attributed_revenue) AS total_revenue
FROM marketing.campaigns
WHERE date_trunc('month', event_date) = date_trunc('month', current_date - interval '1 month')
GROUP BY campaign_name
ORDER BY total_revenue DESC
LIMIT 20

Create a read-only Redshift user:

CREATE USER ivory_agent WITH PASSWORD 'strong_password';
GRANT USAGE ON SCHEMA analytics TO ivory_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO ivory_agent;

Use Redshift Serverless or a standard provisioned cluster — both work with this connection format. For VPC-only clusters, ensure the Ivory Finance agent can reach your cluster endpoint (e.g. via VPC peering or an allow-listed IP).

Google BigQuery

Uses the google-cloud-bigquery client library. Authentication uses Application Default Credentials (ADC) on the server, or a service account key.

Connection string format

bigquery://project_id/dataset_id

Component	Description
`project_id`	Your Google Cloud project ID
`dataset_id`	Default dataset for the query

Example

{
  "query": "What were our top 10 customers by lifetime value?",
  "config": {
    "db_connection_string": "bigquery://my-gcp-project/customer_analytics"
  }
}

The agent writes SQL like this

SELECT customer_id, SUM(order_value) AS lifetime_value
FROM `my-gcp-project.customer_analytics.orders`
GROUP BY customer_id
ORDER BY lifetime_value DESC
LIMIT 10

Setting up service account access

Create a service account

In Google Cloud Console, go to IAM & Admin → Service Accounts → Create Service Account. Name it ivory-agent.

Grant BigQuery Data Viewer

Assign the BigQuery Data Viewer and BigQuery Job User roles to the service account.

Create and download a key

Click Keys → Add Key → Create new key → JSON. Download the key file.

Provide the key to Ivory Finance

Contact support@ivory.finance to securely upload your service account key. It will be stored encrypted and scoped to your account.

BigQuery queries incur per-byte scanning costs. The agent always adds LIMIT 100 to cap result size, but for very large tables consider creating materialized views or authorized views with pre-aggregated data to minimise costs.

Security Model

Read-Only Enforcement

The agent rejects any non-SELECT statement for SQL databases. MongoDB queries are restricted to find operations — insert, update, delete, drop are blocked at the driver level.

Encrypted at Rest

Connection strings stored on the Ivory Finance server are encrypted with AES-256 (Fernet). They are never logged, never returned in API responses, and never shared between accounts.

Row Cap

All database queries are capped at 100 rows. This prevents the agent from accidentally consuming large amounts of context or triggering expensive full-table scans.

Per-Request Isolation

Each request with a db_connection_string uses a fresh, short-lived connection that is closed immediately after the query. There is no connection pooling across requests.

Use a dedicated read-only database user. Never provide superuser or admin credentials. Ivory Finance enforces SELECT-only at the application layer, but having a restricted DB user is an additional layer of defence.

Full Configuration Reference

{
  "query": "string — required",
  "company_name": "string — optional company name hint",
  "cik": "string — optional SEC CIK (zero-padded 10 digits)",
  "config": {
    "llm_provider": "openai | anthropic  (default: openai)",
    "llm_model": "gpt-4o | gpt-4o-mini | claude-opus-4-6 | claude-sonnet-4-6 | ...  (default: gpt-4o)",
    "search_provider": "google | bing | duckduckgo | custom  (default: google)",
    "search_api_key": "string — Bing subscription key or custom bearer token  (default: null)",
    "search_custom_url": "string — base URL for custom search provider  (default: null)",
    "db_connection_string": "postgresql:// | mysql:// | mariadb:// | mongodb:// | oracle:// | redshift:// | snowflake:// | databricks:// | bigquery://  (default: server Postgres)"
  }
}

Code Examples

import httpx
import json

url = "https://api.ivory.finance/v1/rag/answer/agent"
headers = {
    "X-API-Key": "your_ivory_api_key",
    "Accept": "text/event-stream",
    "Content-Type": "application/json",
}
body = {
    "query": "What were Microsoft's cloud revenue figures in the last four quarters?",
    "cik": "0000789019",
    "config": {
        "llm_provider": "openai",
        "llm_model": "gpt-4o",
        "db_connection_string": "postgresql://user:pass@your-db.com:5432/financials"
    }
}

with httpx.stream("POST", url, headers=headers, json=body, timeout=60) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            if event["type"] == "token":
                print(event["token"], end="", flush=True)
            elif event["type"] == "agent_step":
                print(f"\n[{event['status']}] {event['tool']}")
            elif event["type"] == "done":
                print("\n\nDone.")
                break

Companies

Topics

Filings

Press Releases

Presentations

Financial Statements

Earnings

Intelligence Editor

Agentic RAG

Documents

News

Real-Time

Insider Trades

Tools

Alternative Data

Export

Share

Admin

Authentication

Real-Time Database

AI Foundry

ETL Connectors

Lakehouse

Portfolios

Deals

KYC

ESG

Mandates

Forensics

Documentation Index

​LLM Providers

​OpenAI

​Available models

​Example request

​Getting your OpenAI API key

​Anthropic — Claude

​Available models

​Example request

​Getting your Anthropic API key

​Web Search Providers

​Google

​Sub-engines available

​Example request

​Microsoft Bing

​Getting a Bing Search API key

​Example request

​DuckDuckGo

​Example request

​Custom Search Endpoint

​Expected contract

​Example — internal search service

​Example — Search1API aggregator

​Database Connections

​PostgreSQL

​Connection string format

​Example

​The agent writes SQL like this

​Hosted PostgreSQL services

​MySQL

​Connection string format

​Example

​The agent writes SQL like this

​Hosted MySQL services

​MariaDB

​Connection string format

​Example

​Hosted MariaDB services

​MongoDB

​Connection string format

​Example

​The agent generates MongoDB queries like this

​Hosted MongoDB services

​Oracle Database

​Connection string format

​Example

​The agent writes SQL like this

​Data Warehouses & Lakehouses

​Snowflake

​Connection string format

​Example

LLM Providers

OpenAI

Available models

Example request

Getting your OpenAI API key

Anthropic — Claude

Available models

Example request

Getting your Anthropic API key

Web Search Providers

Google

Sub-engines available

Example request

Microsoft Bing

Getting a Bing Search API key

Example request

DuckDuckGo

Example request

Custom Search Endpoint

Expected contract

Example — internal search service

Example — Search1API aggregator

Database Connections

PostgreSQL

Connection string format

Example

The agent writes SQL like this

Hosted PostgreSQL services

MySQL

Connection string format

Example

The agent writes SQL like this

Hosted MySQL services

MariaDB

Connection string format

Example

Hosted MariaDB services

MongoDB

Connection string format

Example

The agent generates MongoDB queries like this

Hosted MongoDB services

Oracle Database

Connection string format

Example

The agent writes SQL like this

Data Warehouses & Lakehouses

Snowflake

Connection string format

Example

The agent writes SQL like this

Databricks SQL

Connection string format

Getting the HTTP path

Example

Amazon Redshift

Connection string format

Example

The agent writes SQL like this

Google BigQuery

Connection string format

Example

The agent writes SQL like this

Setting up service account access

Security Model

Full Configuration Reference

Code Examples