ai

AI-related commands: chat with the AI agents configured on your maps (aifeature), and access CARTO's LLM proxy with an OpenAI-compatible API (aiproxy).

carto aifeature aiagent <map-id>

Chat with the AI agent configured on a specific map. The CLI automatically fetches the agent's configuration and token — you just need your regular CARTO authentication.

# Interactive multi-turn conversation
carto aifeature aiagent <map-id>

# Example session:
# You: What are the traffic patterns in this area?
# Assistant: Based on the data, I can see...
# You: Show me the collision hotspots
# Assistant: Here are the areas with highest collisions...
# You: exit

# One-shot mode
carto aifeature aiagent <map-id> "What are the traffic patterns?"

# Continue a previous conversation
carto aifeature aiagent <map-id> "Tell me more" --conversation-id abc123

# Read message from a file
carto aifeature aiagent <map-id> --file test-query.txt

# Pipe via stdin
echo "Analyze the collision data" | carto aifeature aiagent <map-id>

# JSON output
carto aifeature aiagent <map-id> "Summarize the data" --json

Options:

Option	Description
--conversation-id <id>	Continue a previous conversation by ID.
--file <path>	Read the message from a file.
--json	Machine-readable JSON output (for automation and CI tests).

How it works:

• Connects to your map's configured AI agent.

• The agent has access to map data, workflows, and configured tools.

• Streams responses in real time.

• Executes backend tools (workflows, SQL) automatically.

• Tracks conversation history for multi-turn interactions.

Use cases:

• Test agent instructions — validate behavior during development.

• Debug agent tools — see which workflows/tools the agent invokes.

• Automated testing — agent quality scripts.

• Agent development — rapidly iterate on configuration.

• CI/CD integration — gate deployments on agent validation.

carto aiproxy

Access CARTO's LLM infrastructure directly with an OpenAI-compatible API. Use any available model for custom tasks without going through the AI Features layer.

The CLI automatically connects to CARTO's LiteLLM service at https://litellm-{tenant}.api.carto.com using your CARTO authentication.

carto aiproxy info

Get connection information for external tools.

carto aiproxy info

Example output:

CARTO LiteLLM Proxy Configuration

API Mode:     OpenAI Compatible
API Host:     https://litellm-gcp-us-east1.api.carto.com
API Base URL: https://litellm-gcp-us-east1.api.carto.com/v1
API Key:      eyJhbGciOiJSUzI1NiIs...

Endpoints:
  Chat completions: /v1/chat/completions
  Completions:      /v1/completions
  Embeddings:       /v1/embeddings
  Models:           /v1/models

carto aiproxy models

List available models.

carto aiproxy models

carto aiproxy chat <message>

Send a chat message to a model.

# Simple chat
carto aiproxy chat "What is 2+2?" --model gpt-4

# With a system prompt
carto aiproxy chat "Analyze this data pattern" \
  --model gemini-2.5-flash \
  --system "You are a geospatial data analyst"

# Control generation parameters
carto aiproxy chat "Write a haiku about maps" \
  --model gpt-4 \
  --temperature 1.5 \
  --max-tokens 100

# Read message from a file
carto aiproxy chat --file prompt.txt --model gpt-4

# Pipe via stdin
echo "Explain quantum physics simply" | carto aiproxy chat --model gpt-4

# JSON output
carto aiproxy chat "Hello" --model gpt-4 --json

Options:

Option	Description
--model <name>	(Required) Model to use. Run carto aiproxy models to list available models.
--system <text>	System prompt to set agent behavior.
--temperature <n>	Sampling temperature, 0–2 (default: 1). Higher = more creative.
--max-tokens <n>	Maximum tokens in the response.
--top-p <n>	Top-p sampling, 0–1 (default: 1).
--file <path>	Read the message from a file.
--json	Output the raw JSON response.

Use cases:

• Quick LLM access — use CARTO's LLM infrastructure for any task.

• Prototyping — test prompts before building AI Features.

• Data analysis — get AI insights on your geospatial data.

• Custom scripts — integrate LLM capabilities into automation.

• Model comparison — test the same prompt against different models.