How to Use Agents - Mindsdb

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

<Tip> Learn more about [MindsDB Agents here](/mindsdb_sql/agents/agent). </Tip>

Create Agents

Here is the syntax for creating an agent:

python

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

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.
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="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.

python

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

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

"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 to be used by the agent.
tables stores the list of tables from data sources connected to MindsDB.

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

python

        ...
        data={
            'knowledge_bases': ['project_name.*', ...]
            'tables': ['datasource_conn_name.*', ...]
        },
        ...

</Note>

`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

agent = server.agents.get('sales_agent')

Query Agents

Query an agent to generate responses to questions.

python

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

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

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

server.agents.drop('my_agent')