--- title: "Agent Intelligence API" description: "Pre-run intelligence briefings for AI agents — signals, correlations, market regime, trending companies, and actionable recommendations" canonical: "https://docs.ainative.studio/docs/api/agent-intelligence-api" last-updated: "2026-11-02T18:12:43.468Z" --- # Agent Intelligence API Source: https://docs.ainative.studio/docs/api/agent-intelligence-api > Pre-run intelligence briefings for AI agents — signals, correlations, market regime, trending companies, and actionable recommendations ## Agent Intelligence API The Agent Intelligence API provides pre-run briefings that feed lakehouse-derived insights directly into agent execution cycles. Agents call this endpoint before each run to make data-informed decisions. ## Architecture ``` 30 Data Sources → Lakehouse → 6 Cross-Correlation Algos → Signals + KG ↓ Agent Actions ← Recommendations ← Agent Briefing API ← Pattern Detection ↓ Outcomes → RLHF Scoring → Lakehouse → Better Algos → ... ``` ## Internal Endpoint (Agent Swarm) Used by the 22-agent OpenClaw swarm and Celery cloud agents. ### GET `/api/v1/internal/intelligence/agent-briefing` Returns a tailored intelligence briefing based on the agent's role. **Headers:** - `X-Internal-API-Key` (required) **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `agent` | string | `ir_agent` | Agent name (determines which signals/algos are relevant) | | `since_hours` | int | `24` | How far back to look for fresh signals | | `limit` | int | `50` | Max signals/correlations to return | **Supported Agents:** | Agent | Signals | Algos | |-------|---------|-------| | `ir_agent` / `ainative_ir` | acquisition_opportunity, competitive_filing | developer_influence, content_intelligence | | `sales_agent` | acquisition_opportunity, competitive_filing | acquisition_signal, developer_influence | | `scout` | competitive_filing | content_intelligence, market_sentiment | | `vega` | competitive_filing | market_sentiment | | `vp_marketing` | competitive_filing | market_sentiment, content_intelligence | | `cfo` | — | market_sentiment | | `scc_outreach` | acquisition_opportunity | acquisition_signal, environmental_risk | | `acquireos` | acquisition_opportunity | acquisition_signal | | `cos` | acquisition_opportunity, competitive_filing | market_sentiment | | `research` | — | content_intelligence | **Response:** ```json { "agent": "ir_agent", "timestamp": "2026-06-19T09:41:36Z", "signals": [ { "id": "abc123", "type": "acquisition_opportunity", "algo": "algo_acquisition", "payload": { "address": "371 Calabasas Rd", "apn": "123-456-789", "foreclosure_amount": "949317", "city": "Watsonville" }, "created_at": "2026-06-19T08:00:00Z" } ], "correlations": [ { "algo": "developer_influence", "entity_a": "anthropics/claude-code", "entity_b": "anthropics", "type": "repo_influence_score", "score": 266554.0, "metadata": {"stars": 133277, "commits_90d": 0, "language": "Python"} } ], "market_regime": { "regime": "risk_on", "vix": 18.44, "sp500": 7420.10, "fed_funds": 3.63, "yield_curve": 0.29, "unemployment": 4.3 }, "trending_companies": [ {"name": "Claude", "mention_score": 1.0}, {"name": "Anthropic", "mention_score": 1.0}, {"name": "Cursor", "mention_score": 0.9} ], "recommendations": [ "Market is risk-on — emphasize growth, innovation, speed", "214 new acquisition opportunities detected — prioritize outreach", "Trending in content: Claude, Anthropic, Cursor — reference in outreach" ] } ``` ### POST `/api/v1/internal/intelligence/consume-signal` Marks a signal as consumed by an agent to prevent re-processing. **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `signal_id` | string | Signal ID from the briefing | | `agent` | string | Agent name consuming the signal | **Response:** ```json {"status": "ok", "signal_id": "abc123", "consumed_by": "ir_agent"} ``` ## Cross-Correlation Algorithms Six algorithms run daily to produce signals and correlations: | # | Algorithm | Input Datasets | Output | |---|-----------|---------------|--------| | 1 | **Acquisition Signal Detector** | SCR foreclosures + SCC parcels + SMB | Acquisition opportunity signals | | 2 | **Environmental Risk Scorer** | PurpleAir + USGS Water + Earthquakes | Per-location risk scores | | 3 | **Developer Influence Ranker** | GitHub repos + CRM contacts | Influence scores per developer/repo | | 4 | **Market Sentiment Tracker** | FRED + Yahoo Finance + BLS + Treasury | Market regime classification | | 5 | **Content Intelligence Extractor** | 833 transcripts (YC, TWiST, Anthropic) | Company mention KG edges | | 6 | **Competitive Movement Detector** | SEC EDGAR 8-K + GitHub activity | Competitive filing signals | ## Data Sources Feeding the Intelligence Layer 30 data sources across 5 domains: - **15 Sensor/Environmental:** USGS, PurpleAir, AirNow, IRIS Seismic, RIPE Atlas, TeleGeography, etc. - **8 Financial/Economic:** FRED, Treasury, BLS, World Bank, SEC EDGAR, Census, Yahoo Finance - **Business/CRM:** 291K SMB businesses, 25K CRM contacts, 733 GitHub repos - **Property:** 97K SCC parcels, 903 SCR newspaper records (grant deeds, foreclosures) - **Research:** 833 transcripts (YC, TWiST, Anthropic, Diamandis), 232 PG essays ## Usage in Agent Scripts ```python import requests INTERNAL_KEY = os.environ["AINATIVE_INTERNAL_API_KEY"] BASE_URL = "https://api.ainative.studio" def get_briefing(agent_name: str) -> dict: """Get intelligence briefing before agent run.""" r = requests.get( f"{BASE_URL}/api/v1/internal/intelligence/agent-briefing", params={"agent": agent_name, "since_hours": 24}, headers={"X-Internal-API-Key": INTERNAL_KEY}, ) return r.json() def consume_signal(signal_id: str, agent_name: str): """Mark signal as consumed after acting on it.""" requests.post( f"{BASE_URL}/api/v1/internal/intelligence/consume-signal", params={"signal_id": signal_id, "agent": agent_name}, headers={"X-Internal-API-Key": INTERNAL_KEY}, ) ## Example: IR Agent with intelligence briefing = get_briefing("ir_agent") ## Use market regime to select email template if briefing["market_regime"]["regime"] == "risk_on": template = "growth_focused" else: template = "stability_focused" ## Prioritize contacts at trending companies trending = {c["name"] for c in briefing["trending_companies"]} ## Act on acquisition signals for signal in briefing["signals"]: if signal["type"] == "acquisition_opportunity": process_acquisition_lead(signal["payload"]) consume_signal(signal["id"], "ir_agent") ``` ## Public REST endpoints (planned — not yet available) The signal-bus API documented above is live today. The following **public REST endpoints are not yet released** — they are planned as an Enterprise add-on ($999/mo). They are listed here for roadmap visibility only; calling them today returns 404. - `GET /v1/intelligence/property` — Property + environmental + parcel data - `GET /v1/intelligence/environment` — AQI + seismic + flood risk scores - `GET /v1/intelligence/business` — SMB + developer + corporate intelligence - `GET /v1/intelligence/infrastructure` — Network topology + cable routes - `GET /v1/intelligence/briefing` — Custom agent briefings for developer-built agents The full Intelligence Layer roadmap is planned separately.