Skip to main content
POST
/
agents
Create Agent
curl --request POST \
  --url https://api.contextual.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "system_prompt": "<string>",
  "no_retrieval_system_prompt": "<string>",
  "multiturn_system_prompt": "<string>",
  "filter_prompt": "<string>",
  "suggested_queries": [
    "<string>"
  ],
  "agent_configs": {
    "retrieval_config": {
      "top_k_retrieved_chunks": 123,
      "lexical_alpha": 123,
      "semantic_alpha": 123
    },
    "filter_and_rerank_config": {
      "top_k_reranked_chunks": 123,
      "reranker_score_filter_threshold": 0,
      "rerank_instructions": "<string>",
      "default_metadata_filters": {
        "operator": "AND"
      },
      "per_datastore_metadata_filters": {}
    },
    "generate_response_config": {
      "max_new_tokens": 123,
      "temperature": 123,
      "top_p": 123,
      "frequency_penalty": 123,
      "seed": 123,
      "calculate_groundedness": true,
      "avoid_commentary": false
    },
    "global_config": {
      "enable_rerank": true,
      "enable_filter": true,
      "enable_multi_turn": true,
      "should_check_retrieval_need": true
    },
    "reformulation_config": {
      "enable_query_expansion": true,
      "query_expansion_prompt": "<string>",
      "enable_query_decomposition": true,
      "query_decomposition_prompt": "<string>"
    },
    "acl_config": {
      "acl_active": true,
      "acl_yaml": "<string>"
    },
    "translation_config": {
      "translate_needed": true,
      "translate_confidence": 123
    }
  },
  "description": "",
  "template_name": "default",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
import requests

url = "https://api.contextual.ai/v1/agents"

payload = {
    "name": "<string>",
    "system_prompt": "<string>",
    "no_retrieval_system_prompt": "<string>",
    "multiturn_system_prompt": "<string>",
    "filter_prompt": "<string>",
    "suggested_queries": ["<string>"],
    "agent_configs": {
        "retrieval_config": {
            "top_k_retrieved_chunks": 123,
            "lexical_alpha": 123,
            "semantic_alpha": 123
        },
        "filter_and_rerank_config": {
            "top_k_reranked_chunks": 123,
            "reranker_score_filter_threshold": 0,
            "rerank_instructions": "<string>",
            "default_metadata_filters": { "operator": "AND" },
            "per_datastore_metadata_filters": {}
        },
        "generate_response_config": {
            "max_new_tokens": 123,
            "temperature": 123,
            "top_p": 123,
            "frequency_penalty": 123,
            "seed": 123,
            "calculate_groundedness": True,
            "avoid_commentary": False
        },
        "global_config": {
            "enable_rerank": True,
            "enable_filter": True,
            "enable_multi_turn": True,
            "should_check_retrieval_need": True
        },
        "reformulation_config": {
            "enable_query_expansion": True,
            "query_expansion_prompt": "<string>",
            "enable_query_decomposition": True,
            "query_decomposition_prompt": "<string>"
        },
        "acl_config": {
            "acl_active": True,
            "acl_yaml": "<string>"
        },
        "translation_config": {
            "translate_needed": True,
            "translate_confidence": 123
        }
    },
    "description": "",
    "template_name": "default",
    "datastore_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    system_prompt: '<string>',
    no_retrieval_system_prompt: '<string>',
    multiturn_system_prompt: '<string>',
    filter_prompt: '<string>',
    suggested_queries: ['<string>'],
    agent_configs: {
      retrieval_config: {top_k_retrieved_chunks: 123, lexical_alpha: 123, semantic_alpha: 123},
      filter_and_rerank_config: {
        top_k_reranked_chunks: 123,
        reranker_score_filter_threshold: 0,
        rerank_instructions: '<string>',
        default_metadata_filters: {operator: 'AND'},
        per_datastore_metadata_filters: {}
      },
      generate_response_config: {
        max_new_tokens: 123,
        temperature: 123,
        top_p: 123,
        frequency_penalty: 123,
        seed: 123,
        calculate_groundedness: true,
        avoid_commentary: false
      },
      global_config: {
        enable_rerank: true,
        enable_filter: true,
        enable_multi_turn: true,
        should_check_retrieval_need: true
      },
      reformulation_config: {
        enable_query_expansion: true,
        query_expansion_prompt: '<string>',
        enable_query_decomposition: true,
        query_decomposition_prompt: '<string>'
      },
      acl_config: {acl_active: true, acl_yaml: '<string>'},
      translation_config: {translate_needed: true, translate_confidence: 123}
    },
    description: '',
    template_name: 'default',
    datastore_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://api.contextual.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.contextual.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'system_prompt' => '<string>',
    'no_retrieval_system_prompt' => '<string>',
    'multiturn_system_prompt' => '<string>',
    'filter_prompt' => '<string>',
    'suggested_queries' => [
        '<string>'
    ],
    'agent_configs' => [
        'retrieval_config' => [
                'top_k_retrieved_chunks' => 123,
                'lexical_alpha' => 123,
                'semantic_alpha' => 123
        ],
        'filter_and_rerank_config' => [
                'top_k_reranked_chunks' => 123,
                'reranker_score_filter_threshold' => 0,
                'rerank_instructions' => '<string>',
                'default_metadata_filters' => [
                                'operator' => 'AND'
                ],
                'per_datastore_metadata_filters' => [
                                
                ]
        ],
        'generate_response_config' => [
                'max_new_tokens' => 123,
                'temperature' => 123,
                'top_p' => 123,
                'frequency_penalty' => 123,
                'seed' => 123,
                'calculate_groundedness' => true,
                'avoid_commentary' => false
        ],
        'global_config' => [
                'enable_rerank' => true,
                'enable_filter' => true,
                'enable_multi_turn' => true,
                'should_check_retrieval_need' => true
        ],
        'reformulation_config' => [
                'enable_query_expansion' => true,
                'query_expansion_prompt' => '<string>',
                'enable_query_decomposition' => true,
                'query_decomposition_prompt' => '<string>'
        ],
        'acl_config' => [
                'acl_active' => true,
                'acl_yaml' => '<string>'
        ],
        'translation_config' => [
                'translate_needed' => true,
                'translate_confidence' => 123
        ]
    ],
    'description' => '',
    'template_name' => 'default',
    'datastore_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.contextual.ai/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"no_retrieval_system_prompt\": \"<string>\",\n  \"multiturn_system_prompt\": \"<string>\",\n  \"filter_prompt\": \"<string>\",\n  \"suggested_queries\": [\n    \"<string>\"\n  ],\n  \"agent_configs\": {\n    \"retrieval_config\": {\n      \"top_k_retrieved_chunks\": 123,\n      \"lexical_alpha\": 123,\n      \"semantic_alpha\": 123\n    },\n    \"filter_and_rerank_config\": {\n      \"top_k_reranked_chunks\": 123,\n      \"reranker_score_filter_threshold\": 0,\n      \"rerank_instructions\": \"<string>\",\n      \"default_metadata_filters\": {\n        \"operator\": \"AND\"\n      },\n      \"per_datastore_metadata_filters\": {}\n    },\n    \"generate_response_config\": {\n      \"max_new_tokens\": 123,\n      \"temperature\": 123,\n      \"top_p\": 123,\n      \"frequency_penalty\": 123,\n      \"seed\": 123,\n      \"calculate_groundedness\": true,\n      \"avoid_commentary\": false\n    },\n    \"global_config\": {\n      \"enable_rerank\": true,\n      \"enable_filter\": true,\n      \"enable_multi_turn\": true,\n      \"should_check_retrieval_need\": true\n    },\n    \"reformulation_config\": {\n      \"enable_query_expansion\": true,\n      \"query_expansion_prompt\": \"<string>\",\n      \"enable_query_decomposition\": true,\n      \"query_decomposition_prompt\": \"<string>\"\n    },\n    \"acl_config\": {\n      \"acl_active\": true,\n      \"acl_yaml\": \"<string>\"\n    },\n    \"translation_config\": {\n      \"translate_needed\": true,\n      \"translate_confidence\": 123\n    }\n  },\n  \"description\": \"\",\n  \"template_name\": \"default\",\n  \"datastore_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.contextual.ai/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"no_retrieval_system_prompt\": \"<string>\",\n  \"multiturn_system_prompt\": \"<string>\",\n  \"filter_prompt\": \"<string>\",\n  \"suggested_queries\": [\n    \"<string>\"\n  ],\n  \"agent_configs\": {\n    \"retrieval_config\": {\n      \"top_k_retrieved_chunks\": 123,\n      \"lexical_alpha\": 123,\n      \"semantic_alpha\": 123\n    },\n    \"filter_and_rerank_config\": {\n      \"top_k_reranked_chunks\": 123,\n      \"reranker_score_filter_threshold\": 0,\n      \"rerank_instructions\": \"<string>\",\n      \"default_metadata_filters\": {\n        \"operator\": \"AND\"\n      },\n      \"per_datastore_metadata_filters\": {}\n    },\n    \"generate_response_config\": {\n      \"max_new_tokens\": 123,\n      \"temperature\": 123,\n      \"top_p\": 123,\n      \"frequency_penalty\": 123,\n      \"seed\": 123,\n      \"calculate_groundedness\": true,\n      \"avoid_commentary\": false\n    },\n    \"global_config\": {\n      \"enable_rerank\": true,\n      \"enable_filter\": true,\n      \"enable_multi_turn\": true,\n      \"should_check_retrieval_need\": true\n    },\n    \"reformulation_config\": {\n      \"enable_query_expansion\": true,\n      \"query_expansion_prompt\": \"<string>\",\n      \"enable_query_decomposition\": true,\n      \"query_decomposition_prompt\": \"<string>\"\n    },\n    \"acl_config\": {\n      \"acl_active\": true,\n      \"acl_yaml\": \"<string>\"\n    },\n    \"translation_config\": {\n      \"translate_needed\": true,\n      \"translate_confidence\": 123\n    }\n  },\n  \"description\": \"\",\n  \"template_name\": \"default\",\n  \"datastore_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.contextual.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"no_retrieval_system_prompt\": \"<string>\",\n  \"multiturn_system_prompt\": \"<string>\",\n  \"filter_prompt\": \"<string>\",\n  \"suggested_queries\": [\n    \"<string>\"\n  ],\n  \"agent_configs\": {\n    \"retrieval_config\": {\n      \"top_k_retrieved_chunks\": 123,\n      \"lexical_alpha\": 123,\n      \"semantic_alpha\": 123\n    },\n    \"filter_and_rerank_config\": {\n      \"top_k_reranked_chunks\": 123,\n      \"reranker_score_filter_threshold\": 0,\n      \"rerank_instructions\": \"<string>\",\n      \"default_metadata_filters\": {\n        \"operator\": \"AND\"\n      },\n      \"per_datastore_metadata_filters\": {}\n    },\n    \"generate_response_config\": {\n      \"max_new_tokens\": 123,\n      \"temperature\": 123,\n      \"top_p\": 123,\n      \"frequency_penalty\": 123,\n      \"seed\": 123,\n      \"calculate_groundedness\": true,\n      \"avoid_commentary\": false\n    },\n    \"global_config\": {\n      \"enable_rerank\": true,\n      \"enable_filter\": true,\n      \"enable_multi_turn\": true,\n      \"should_check_retrieval_need\": true\n    },\n    \"reformulation_config\": {\n      \"enable_query_expansion\": true,\n      \"query_expansion_prompt\": \"<string>\",\n      \"enable_query_decomposition\": true,\n      \"query_decomposition_prompt\": \"<string>\"\n    },\n    \"acl_config\": {\n      \"acl_active\": true,\n      \"acl_yaml\": \"<string>\"\n    },\n    \"translation_config\": {\n      \"translate_needed\": true,\n      \"translate_confidence\": 123\n    }\n  },\n  \"description\": \"\",\n  \"template_name\": \"default\",\n  \"datastore_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Input to Create Agent request

​
name
string
required

Name of the agent

Required string length: 3 - 200
​
system_prompt
string

Instructions that your agent references when generating responses. Note that we do not guarantee that the system will follow these instructions exactly.

Maximum string length: 8000
​
no_retrieval_system_prompt
string

Instructions on how the agent should respond when there are no relevant retrievals that can be used to answer a query.

Maximum string length: 8000
​
multiturn_system_prompt
string

Instructions on how the agent should handle multi-turn conversations.

Maximum string length: 8000
​
filter_prompt
string

The prompt to an LLM which determines whether retrieved chunks are relevant to a given query and filters out irrelevant chunks.

Maximum string length: 8000
​
suggested_queries
string[]

These queries will show up as suggestions in the Contextual UI when users load the agent. We recommend including common queries that users will ask, as well as complex queries so users understand the types of complex queries the system can handle. The max length of all the suggested queries is 1000.

​
agent_configs
Agent Configs · object

The following advanced parameters are experimental and subject to change.

​
description
string
default:""

Description of the agent

Maximum string length: 500
​
template_name
default:default

The template defining the base configuration for the agent. This can be a built-in template (DefaultTemplateName) or a custom template name

Available options:
default,
finance,
customer_support,
company_policy_q_and_a
​
datastore_ids
string<uuid>[]

The IDs of the datastore to associate with this agent.

Response

Successful Response

Response to POST /agents request

​
id
string<uuid>
required

ID of the agent

​
datastore_ids
string<uuid>[]
required

IDs of the datastores associated with the agent. If no datastore was provided as part of the request, this is a singleton list containing the ID of the automatically created datastore.