# 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.

```bash
# 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.

```bash
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.

```bash
carto aiproxy models
```

### `carto aiproxy chat <message>`

Send a chat message to a model.

```bash
# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-agents/cli/command-reference/ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.