> ## 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.
Learn more about [MindsDB Agents here](/mindsdb_sql/agents/agent).
## Create Agents
Here is the syntax for creating an agent:
```python theme={null}
agent = server.agents.create(
'my_agent',
model={
'model_name': 'gpt-4o',
'provider': 'openai',
'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'
)
```
It creates an agent that uses the defined model and has access to the connected data. Here is how to list all available agents.
```python theme={null}
agents = server.agents.list()
print(agents)
```
The following sections explain all the agent parameters.
### `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.
Available models:
* claude-3-opus-20240229
* claude-3-sonnet-20240229
* claude-3-haiku-20240307
* claude-2.1
* claude-2.0
* claude-instant-1.2
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
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
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
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
Available models:
* palmyra-x5
* palmyra-x4
Users can define the model for the agent choosing one of the following options.
**Option 1.** Use the `model` parameter to define the specification.
```python theme={null}
...
model={
'model_name': 'gpt-4o',
'provider': 'openai',
'api_key': 'sk-abc123',
'base_url': 'http://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.
You can define the default models in the Settings of the MindsDB Editor GUI.
```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.
Note that you can insert all tables from a connected data source and all knowledge bases from a project using the `*` syntax.
```python theme={null}
...
data={
'knowledge_bases': ['project_name.*', ...]
'tables': ['datasource_conn_name.*', ...]
},
...
```
### `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.
## Get Agents
You can get an existing agent with the `get()` method.
```python theme={null}
agent = server.agents.get('sales_agent')
```
## Query Agents
Query an agent to generate responses to questions.
```python theme={null}
completion = agent.completion([{'question': 'What is the average number of orders per customers?', 'answer': None}])
print(completion.content)
```
Here is how to query agents with enabled streaming, allowing users to view agent's thoughts when it is working on answering questions.
```python theme={null}
completion = agent.completion_stream([{'question': 'What is the average number of orders per customers?', 'answer': None}])
for chunk in completion:
print(chunk)
```
## Update Agents
Update existing agents with new data, model, or prompt.
```python theme={null}
agent.data['tables'].append('mysql_demo_db.car_sales')
updated_agent = server.agents.update('my_agent', agent)
print(updated_agent)
```
## Delete Agents
Here is the syntax for deleting an agent:
```python theme={null}
server.agents.drop('my_agent')
```