/agents

Create Agent

Create a new Agent with a specific configuration.

This creates a specialized RAG Agent which queries over one or multiple Datastores to retrieve relevant data on which its generations are grounded.

Retrieval and generation parameters are defined in the provided Agent configuration.

If no datastore_id is provided in the configuration, this API automatically creates an empty Datastore and configures the Agent to use the newly created Datastore.

Note that self-serve users are currently required to create agents through our UI. Otherwise, they will receive the following message: “This endpoint is disabled as you need to go through checkout. Please use the UI to make this request.”

POST

agents

curl --request POST \
  --url https://api.contextual.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "system_prompt": "<string>",
  "no_retrieval_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": 123,
      "rerank_instructions": "<string>"
    },
    "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
    }
  },
  "name": "<string>",
  "description": "",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

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

object

The following advanced parameters are experimental and subject to change.

agent_configs.retrieval_config

object

Parameters that affect how the agent retrieves from datastore(s)

agent_configs.filter_and_rerank_config

object

Parameters that affect filtering and reranking of retrieved knowledge

agent_configs.generate_response_config

object

Parameters that affect response generation

agent_configs.global_config

object

Parameters that affect the agent's overall RAG workflow

description

string

default:

Description of the agent

Maximum length: 500

datastore_ids

string[]

The IDs of the datastore to associate with this agent.

Response

200

application/json

Successful Response

Response to POST /agents request

string

required

ID of the agent

datastore_ids

string[]

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.

Was this page helpful?

List Agents Edit Agent

curl --request POST \
  --url https://api.contextual.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "system_prompt": "<string>",
  "no_retrieval_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": 123,
      "rerank_instructions": "<string>"
    },
    "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
    }
  },
  "name": "<string>",
  "description": "",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

/datastores

/datastores/{id}/documents

/agents

/agents/{id}/query

/agents/{id}/evaluate

/agents/{id}/datasets/evaluate

/agents/{id}/datasets/tune

/agents/{id}/tune

/lmunit

/users

/generate

/rerank

Create Agent

Authorizations

Body

Response