> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Use Agents

Agents enable conversation with data, including structured and unstructured data connected to MindsDB.

## `CREATE AGENT` Syntax

Here is the syntax for creating an agent:

```sql theme={null}
CREATE AGENT my_agent
USING
    model = {
        "provider": "openai",
        "model_name" : "gpt-4o",
        "api_key": "sk-abc123",
        "base_url": "http://example.com",
        "api_version": "2024-02-01"
    },
    data = {
         "knowledge_bases": ["project_name.kb_name", ...],
         "tables": ["datasource_conn_name.table_name", ...]
    },
    prompt_template='describe data',
    timeout=10,
    mode='text';
```

It creates an agent that uses the defined model and has access to the connected data.

```sql theme={null}
SHOW AGENTS
WHERE name = 'my_agent';
```

<Note>
  Note that you can insert all tables from a connected data source and all knowledge bases from a project using the `*` syntax.

  ```sql theme={null}
      ...
      data = {
           "knowledge_bases": ["project_name.*", ...],
           "tables": ["datasource_conn_name.*", ...]
      },
      ...
  ```
</Note>

### `model`

This parameter defines the underlying language model, including:

* `provider`
  It is a required parameter. It defines the model provider from the list below.

* `model_name`
  It is a required parameter. It defines the model name from the list below.

* `api_key`
  It is an optional parameter (applicable to selected providers), which stores the API key to access the model. Users can provide it either in this `api_key` parameter, or using [environment variables](/mindsdb_sql/functions/from_env).

* `base_url`
  It is an optional parameter (applicable to selected providers), which stores the base URL for accessing the model. It is the root URL used to send API requests.

* `api_version`
  It is an optional parameter (applicable to selected providers), which defines the API version.

The available models and providers include the following.

<AccordionGroup>
  <Accordion title="Anthropic">
    Available models:

    * claude-3-opus-20240229
    * claude-3-sonnet-20240229
    * claude-3-haiku-20240307
    * claude-2.1
    * claude-2.0
    * claude-instant-1.2
  </Accordion>

  <Accordion title="Bedrock">
    Available models include all models accessible from Bedrock.

    Note that in order to use Bedrock as a model provider, you should ensure the following packages are installed: `langchain_aws` and `transformers`.

    The following parameters are specific to this provider:

    * `aws_region_name` is a required parameter.
    * `aws_access_key_id` is a required parameter.
    * `aws_secret_access_key` is a required parameter.
    * `aws_session_token` is an optional parameter. It may be required depending on the AWS permissions setup.
  </Accordion>

  <Accordion title="Google">
    Available models:

    * gemini-2.5-pro-preview-03-25
    * gemini-2.0-flash
    * gemini-2.0-flash-lite
    * gemini-1.5-flash
    * gemini-1.5-flash-8b
    * gemini-1.5-pro
  </Accordion>

  <Accordion title="Ollama">
    Available models:

    * gemma
    * llama2
    * mistral
    * mixtral
    * llava
    * neural-chat
    * codellama
    * dolphin-mixtral
    * qwen
    * llama2-uncensored
    * mistral-openorca
    * deepseek-coder
    * nous-hermes2
    * phi
    * orca-mini
    * dolphin-mistral
    * wizard-vicuna-uncensored
    * vicuna
    * tinydolphin
    * llama2-chinese
    * openhermes
    * zephyr
    * nomic-embed-text
    * tinyllama
    * openchat
    * wizardcoder
    * phind-codellama
    * starcoder
    * yi
    * orca2
    * falcon
    * starcoder2
    * wizard-math
    * dolphin-phi
    * nous-hermes
    * starling-lm
    * stable-code
    * medllama2
    * bakllava
    * codeup
    * wizardlm-uncensored
    * solar
    * everythinglm
    * sqlcoder
    * nous-hermes2-mixtral
    * stable-beluga
    * yarn-mistral
    * samantha-mistral
    * stablelm2
    * meditron
    * stablelm-zephyr
    * magicoder
    * yarn-llama2
    * wizard-vicuna
    * llama-pro
    * deepseek-llm
    * codebooga
    * mistrallite
    * dolphincoder
    * nexusraven
    * open-orca-platypus2
    * all-minilm
    * goliath
    * notux
    * alfred
    * megadolphin
    * xwinlm
    * wizardlm
    * duckdb-nsql
    * notus
  </Accordion>

  <Accordion title="OpenAI">
    Available models:

    * gpt-3.5-turbo
    * gpt-3.5-turbo-16k
    * gpt-3.5-turbo-instruct
    * gpt-4
    * gpt-4-32k
    * gpt-4-1106-preview
    * gpt-4-0125-preview
    * gpt-4.1
    * gpt-4.1-mini
    * gpt-4o
    * o4-mini
    * o3-mini
    * o1-mini
  </Accordion>

  <Accordion title="Nvidia NIM">
    Available models:

    * microsoft/phi-3-mini-4k-instruct
    * mistralai/mistral-7b-instruct-v0.2
    * writer/palmyra-med-70b
    * mistralai/mistral-large
    * mistralai/codestral-22b-instruct-v0.1
    * nvidia/llama3-chatqa-1.5-70b
    * upstage/solar-10.7b-instruct
    * google/gemma-2-9b-it
    * adept/fuyu-8b
    * google/gemma-2b
    * databricks/dbrx-instruct
    * meta/llama-3\_1-8b-instruct
    * microsoft/phi-3-medium-128k-instruct
    * 01-ai/yi-large
    * nvidia/neva-22b
    * meta/llama-3\_1-70b-instruct
    * google/codegemma-7b
    * google/recurrentgemma-2b
    * google/gemma-2-27b-it
    * deepseek-ai/deepseek-coder-6.7b-instruct
    * mediatek/breeze-7b-instruct
    * microsoft/kosmos-2
    * microsoft/phi-3-mini-128k-instruct
    * nvidia/llama3-chatqa-1.5-8b
    * writer/palmyra-med-70b-32k
    * google/deplot
    * meta/llama-3\_1-405b-instruct
    * aisingapore/sea-lion-7b-instruct
    * liuhaotian/llava-v1.6-mistral-7b
    * microsoft/phi-3-small-8k-instruct
    * meta/codellama-70b
    * liuhaotian/llava-v1.6-34b
    * nv-mistralai/mistral-nemo-12b-instruct
    * microsoft/phi-3-medium-4k-instruct
    * seallms/seallm-7b-v2.5
    * mistralai/mixtral-8x7b-instruct-v0.1
    * mistralai/mistral-7b-instruct-v0.3
    * google/paligemma
    * google/gemma-7b
    * mistralai/mixtral-8x22b-instruct-v0.1
    * google/codegemma-1.1-7b
    * nvidia/nemotron-4-340b-instruct
    * meta/llama3-70b-instruct
    * microsoft/phi-3-small-128k-instruct
    * ibm/granite-8b-code-instruct
    * meta/llama3-8b-instruct
    * snowflake/arctic
    * microsoft/phi-3-vision-128k-instruct
    * meta/llama2-70b
    * ibm/granite-34b-code-instruct
  </Accordion>

  <Accordion title="Writer">
    Available models:

    * palmyra-x5
    * palmyra-x4
  </Accordion>
</AccordionGroup>

Users can define the model for the agent choosing one of the following options.

**Option 1.** Use the `model` parameter to define the specification.

```sql theme={null}
CREATE AGENT my_agent
USING
    model = {
        "provider": "openai",
        "model_name" : "got-4o",
        "api_key": "sk-abc123",
        "base_url": "https://example.com/",
        "api_version": "2024-02-01"
    },
    ...
```

**Option 2.** Define the default model in the [MindsDB configuration file](/setup/custom-config).

If you define `default_llm` in the configuration file, you do not need to provide the `model` parameter when creating an agent. If provide both, then the values from the `model` parameter are used.

<Tip>
  You can define the default models in the Settings of the MindsDB Editor GUI.
</Tip>

```bash theme={null}
"default_llm": {

      "provider": "openai",
      "model_name" : "got-4o",
      "api_key": "sk-abc123",
      "base_url": "https://example.com/",
      "api_version": "2024-02-01"

}
```

### `data`

This parameter stores data connected to the agent, including knowledge bases and data sources connected to MindsDB.

The following parameters store the list of connected data.

* `knowledge_bases` stores the list of [knowledge bases](/mindsdb_sql/knowledge_bases/overview) to be used by the agent.

* `tables` stores the list of tables from data sources connected to MindsDB.

### `prompt_template`

This parameter stores instructions for the agent.

It is recommended to provide data description of the data sources listed in the `knowledge_bases` and `tables` parameters to help the agent locate relevant data for answering questions.

### `timeout`

This parameter defines the time the agent can take to come back with an answer.

For example, when the `timeout` parameter is set to 10, the agent has 10 seconds to return an answer. If the agent takes longer than 10 seconds, it aborts the process and comes back with an answer indicating its failure to return an answer within the defined time interval.

### `mode`

This parameter defines the agent's response style, allowing users to partially control the output format. Supported values include `text` and `sql`.

When set, the agent will tailor its responses to match the specified format. Note that the agent may still adapt its output when necessary to ensure clarity or correctness.

## `SELECT FROM AGENT` Syntax

Query an agent to generate responses to questions.

```sql theme={null}
SELECT answer
FROM my_agent 
WHERE question = 'What is the average number of orders per customers?';

-- or

SELECT customer_name, avg_number_of_orders
FROM my_agent 
WHERE question = 'What is the average number of orders per customers?';
```

You can redefine the agent's parameters at the query time as below.

```sql theme={null}
SELECT answer
FROM my_agent 
WHERE question = 'What is the average number of orders per customers?';
USING
    model = {
        "provider": "openai",
        "model_name" : "gpt-4.1",
        "api_key": "sk-abc123"
    },
    data = {
         "knowledge_bases": ["project_name.kb_name", ...],
         "tables": ["datasource_conn_name.table_name", ...]
    },
    prompt_template='describe data',
    timeout=10;
```

The `USING` clause may contain any combination of parameters from the `CREATE AGENT` command, depending on which parameters users want to update for the query.

For example, users may want to check the performance of other models to decide which model works better for their use case.

```sql theme={null}
SELECT answer
FROM my_agent 
WHERE question = 'What is the average number of orders per customers?';
USING
    model = {
        "provider": "google",
        "model_name" : "gemini-2.5-flash",
        "api_key": "ABc123"
    };
```

## `ALTER AGENT` Syntax

Update existing agents with new data, model, or prompt.

```sql theme={null}
ALTER AGENT my_agent
USING
    model = {
        "provider": "openai",
        "model_name" : "gpt-4.1",
        "api_key": "sk-abc123",
        "base_url": "http://example.com",
        "api_version": "2024-02-01"
    },
    data = {
         "knowledge_bases": ["project_name.kb_name", ...],
         "tables": ["datasource_conn_name.table_name", ...]
    },
    prompt_template='describe data';
```

Note that all parameters are optional. Users can update any combination of parameters.

<Tip>
  See detailed descriptions of parameters in the [`CREATE AGENT` section](/mindsdb_sql/agents/agent_syntax#create-agent-syntax).
</Tip>

Here is how to connect new data to an agent.

```sql theme={null}
ALTER AGENT my_agent
USING
    data = {
         "knowledge_bases": ["mindsdb.sales_kb"],
         "tables": ["mysql_db.car_sales", "mysql_db.car_info"]
    };
```

And here is how to update a model used by the agent.

```sql theme={null}
ALTER AGENT my_agent
USING
    model = {
        "provider": "openai",
        "model_name" : "gpt-4.1",
        "api_key": "sk-abc123"
    };
```

## `DROP AGENT` Syntax

Here is the syntax for deleting an agent:

```sql theme={null}
DROP AGENT my_agent;
```