Agno API

The Agno FastAPI service runs the agent runtime. Laravel calls these endpoints internally over Docker network DNS. All requests require X-Agno-Key: {AGNO_API_KEY} header.

Base URL (internal): http://ubios_agno:8001 (ip-test) or http://agno-api:8001 (production)

Agent Queries

POST /query

Primary endpoint for user-initiated questions. OrchestratorAgent classifies intent and routes to specialist.

Request:

Field	Type	Required	Notes
`question`	string	yes	Natural language question
`user_id`	UUID	yes	For session logging
`session_context`	object	no	Previous messages for multi-turn
`response_format`	string	no	`text`, `table`, `chart`, `auto` (default: `auto`)

Response:

Field	Type	Notes
`answer`	string	Natural language answer
`agent_used`	string	Which specialist handled it
`source`	string	`redis_cache`, `saved_query`, `generated`, `rag`
`data`	object	Structured data (table/chart)
`sql_used`	string	SQL executed (AnalyticsAgent only)
`citations`	array	Source references (KnowledgeAgent only)
`confidence`	float	0–1
`suggested_questions`	array	3 follow-up questions
`session_id`	UUID	For multi-turn conversation
`duration_ms`	integer

POST /context

Context panel data when user clicks a dashboard element. Target: under 1.5 seconds.

Request:

Field	Type	Required	Notes
`click_type`	string	yes	`entity`, `metric`, `alert`
`entity_type`	string	conditional	Required for `entity` clicks
`entity_id`	UUID	conditional	Required for `entity` clicks
`metric_name`	string	conditional	Required for `metric` clicks
`period`	string	conditional	Time period for metric clicks
`agent_output_id`	UUID	conditional	Required for `alert` clicks

Response:

Field	Type	Notes
`title`	string	Context panel headline
`explanation`	string	2–4 sentence explanation
`key_signals`	array	`{label, value, trend}` objects
`recommended_action`	string	What to do (optional)
`suggested_questions`	array	3 drill-down questions
`confidence`	float

Document Extraction

POST /extract

Trigger document extraction. Returns immediately — poll status with job_id.

Request:

Field	Type	Required	Notes
`document_id`	UUID	yes	FK to `tenant_data.documents`
`storage_path`	string	yes	MinIO/S3 path
`mime_type`	string	yes
`document_type`	string	yes	`invoice`, `contract`, `delivery_note`, etc.
`force_ocr`	boolean	no	Skip Docling, use Mistral OCR
`force_table`	boolean	no	Route to PaddleOCR for table-heavy documents

Response: { job_id, estimated_seconds }

GET /extract/status/:job_id

Response:

Field	Type	Notes
`status`	string	`queued`, `parsing`, `extracting`, `validating`, `completed`, `failed`, `review_required`
`progress`	integer	0–100
`fields_extracted`	integer
`fields_flagged`	integer	Low-confidence fields
`error`	string	On failure only

Behavioral Scoring

POST /score

Trigger scoring for one or more entities.

Request:

Field	Type	Required	Notes
`entity_type`	string	yes	e.g. `customer`
`entity_ids`	array	no	Empty = score all
`goal_id`	UUID	no	Empty = all active goals
`force_refresh`	boolean	no	Ignore Redis cache

Response: { job_id, entities_queued }

Web Crawling

POST /crawl

Scrape, crawl, or map a URL via self-hosted Firecrawl. Requires --profile web Docker profile.

Request:

Field	Type	Required	Notes
`url`	string	yes	URL to crawl
`mode`	string	no	`scrape` (default), `crawl`, `map`
`limit`	integer	no	Max pages for crawl mode (default: 10)
`max_depth`	integer	no	Crawl depth (default: 2)

Response:

Field	Type	Notes
`url`	string	The requested URL
`mode`	string	Which mode was used
`pages`	array	`[{url, markdown, title}]` for scrape/crawl, `[{url}]` for map
`total_pages`	integer	Number of pages returned
`duration_ms`	integer

Modes:

scrape — Single page, returns markdown + metadata
crawl — Multi-page, follows links up to limit and max_depth
map — URL discovery only, no content fetched

POST /widget/render

Render widget data. Cache/template hits return in under 100ms. No LLM call for any standard widget.

Request:

Field	Type	Required	Notes
`widget_type`	string	yes	`kpi_card`, `metric_chart`, `top_n_table`, `call_list`, `alert_feed`, `raw_query`, `report`
`config`	object	yes	Widget-specific configuration
`role`	string	no	`admin`, `manager`, `viewer`

Response: { widget_type, data, source, duration_ms }

source values: template (pre-computed), cache (Redis), generated (LLM, admin testing only), pre_computed (from agent_outputs).

GET /widget/suggest

Suggest widget configurations based on the semantic model. Admin-only.

Response: { suggestions: [{ widget_type, config, preview_description }] }

Templates

POST /templates/render

Render a saved query template with parameters.

POST /templates/suggest

Suggest templates based on the semantic model.

POST /templates/chat

Chat about template modifications.

POST /templates/evaluate

Evaluate a template against test data.

POST /templates/summarize

Summarize template results.

System

GET /health

Response:

Field	Type	Notes
`status`	string	`ok`, `degraded`, `unavailable`
`database`	string	`ok`, `error`
`redis`	string	`ok`, `error`
`llm_providers`	object	`provider_name: 'ok' or 'error'` per provider
`version`	string	Agno version
`uptime_seconds`	integer

POST /schema/refresh

Re-sync schema_context from live database DDL.

Response: { tables_synced, columns_synced, duration_ms }

GET /traces/:trace_id

Retrieve a query trace for debugging.

POST /config/reload

Reload configuration from database.

GET /metrics

Prometheus-format metrics for monitoring.

Error Format

All errors return HTTP 4xx/5xx with:

{
  "error": "string description",
  "error_code": "AGENT_TIMEOUT | SCHEMA_NOT_FOUND | LLM_FAILURE | VALIDATION_FAILED",
  "retry_possible": true,
  "details": {}
}