Create Agent

POST /api/projects/{project_name}/agents

This API endpoint creates an agent using the POST method.

Learn more about agents and the available parameters following this doc page.

Path Parameters

project_name · string · required

Defines the project where the agents are located. Note that the default project name is mindsdb.

Body

name · string · required

Name of the agent.

model · string

Stores parameters of the model, including provider, model_name, and api_key. Note that agents can use the default model defined in the configuration, if no model provided when creating an agent.

data · string

Stores data connected to an agent, including tables and knowledge_bases.

prompt_template · string

Stores instruction to an agent. This should contain the description of connected data.

Response

id · string · required

Unique identifier for the agent.

name · string · required

The name assigned to the agent.

project_id · string · required

The ID of the project where the agent resides.

created_at · string · required

Timestamp indicating when the agent was created.

updated_at · string · required

Timestamp indicating when the agent was last updated.

Stores data connected to an agent, including tables and knowledge_bases.

In order to provide all tables from a database or all knowledge bases from a project, use the * wildcard like this:

    "data": {
         "knowledge_bases": ["my_project.*"],
         "tables": ["my_data_source.*"]
    }

Stores parameters of the model, including provider, model_name, and api_key.

Stores instruction to an agent. This should contain the description of connected data.

Shell

curl --request POST \
  --url http://127.0.0.1:47334/api/projects/mindsdb/agents \
  --header 'Content-Type: application/json' \
  --data '{
  "agent": {
    "name": "my_agent",
    "model": {
        "provider": "openai",
        "model_name": "gpt-4o",
        "api_key": "sk-xxx"
    },
    "data": {
         "knowledge_bases": ["my_project.my_kb"],
         "tables": ["my_data_source.my_table"]
    },
    "prompt_template": "my_project.my_kb stores documentation of MindsDB, my_data_source.my_table stores documentation of MindsDB"
  }
}'

Response

{
  "id": 197,
  "name": "my_agent",
  "project_id": 1,
  "created_at": "2025-07-09 12:58:24.868202",
  "updated_at": "2025-07-09 12:58:24.868199",
  "data": {
    "knowledge_bases": [
      "my_project.my_kb"
    ],
    "tables": [
      "my_data_source.my_table"
    ]
  },
  "model": {
    "provider": "openai",
    "model_name": "gpt-4o",
    "api_key": "sk-xxx"
  },
  "prompt_template": "my_project.my_kb stores documentation of MindsDB, my_data_source.my_table stores documentation of MindsDB"
}