Create Agent

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.

Show child attributes

agent_configs.retrieval_config

Retrieval Config · object

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

Show child attributes

agent_configs.retrieval_config.top_k_retrieved_chunks

integer

The maximum number of retrieved chunks from the datastore.

agent_configs.retrieval_config.lexical_alpha

number

The weight of lexical search during retrieval. Must sum to 1 with semantic_alpha.

agent_configs.retrieval_config.semantic_alpha

number

The weight of semantic search during retrieval. Must sum to 1 with lexical_alpha.

agent_configs.filter_and_rerank_config

Filter And Rerank Config · object

Parameters that affect filtering and reranking of retrieved knowledge

Show child attributes

agent_configs.filter_and_rerank_config.top_k_reranked_chunks

integer

The number of highest ranked chunks after reranking to be used

agent_configs.filter_and_rerank_config.reranker_score_filter_threshold

number

default:0

If the reranker relevance score associated with a chunk is below this threshold, then the chunk will be filtered out and not used for generation. Scores are between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 to disable the reranker score filtering.

Required range: 0 <= x <= 1

agent_configs.filter_and_rerank_config.rerank_instructions

string

Instructions that the reranker references when ranking retrievals. Note that we do not guarantee that the reranker will follow these instructions exactly. Examples: "Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications." and "Emphasize forecasts from top-tier investment banks. Recent analysis should take precedence. Disregard aggregator sites and favor detailed research notes over news summaries."

agent_configs.filter_and_rerank_config.default_metadata_filters

BaseMetadataFilter · object

Optional metadata filter which is applied while retrieving from every datastore linked to this agent.

BaseMetadataFilter
CompositeMetadataFilter

Show child attributes

agent_configs.filter_and_rerank_config.default_metadata_filters.field

string

required

Field name to search for in the metadata

agent_configs.filter_and_rerank_config.default_metadata_filters.operator

enum<string>

required

Operator to be used for the filter.

Available options:

equals,

containsany,

exists,

startswith,

gt,

gte,

lt,

lte,

notequals,

between,

wildcard

agent_configs.filter_and_rerank_config.default_metadata_filters.value

The value to be searched for in the field. In case of exists operator, it is not needed.

Example:

{
  "filters": [
    {
      "field": "field1",
      "operator": "equals",
      "value": "value1"
    }
  ],
  "operator": "AND"
}

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters

Per Datastore Metadata Filters · object

Defines an optional custom metadata filter per datastore ID. Each entry in the dictionary should have a datastore UUID as the key, and the value should be a metadata filter definition. The filter will be applied in addition to filter(s) specified in default_metadata_filters and in the documents_filters field in the /query request during retrieval.

Show child attributes

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters.{key}

CompositeMetadataFilter · object

"Defines a custom metadata filter as a Composite MetadataFilter. Which can be be a list of filters or nested filters.

Show child attributes

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters.{key}.filters

BaseMetadataFilter · object[]

required

Filters added to the query for filtering docs

Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example:

{"field": "title", "operator": "startswith", "value": "hr-"}

Use lowercase for value when not using equals operator. For document_id and date_created the query is built using direct query without nesting.

Show child attributes

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters.{key}.filters.field

string

required

Field name to search for in the metadata

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters.{key}.filters.operator

enum<string>

required

Operator to be used for the filter.

Available options:

equals,

containsany,

exists,

startswith,

gt,

gte,

lt,

lte,

notequals,

between,

wildcard

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters.{key}.filters.value

The value to be searched for in the field. In case of exists operator, it is not needed.

agent_configs.filter_and_rerank_config.per_datastore_metadata_filters.{key}.operator

enum<string> | null

Composite operator to be used to combine filters

Available options:

AND,

OR,

AND_NOT

agent_configs.generate_response_config

Generate Response Config · object

Parameters that affect response generation

Show child attributes

agent_configs.generate_response_config.model

enum<string>

The model to use for response generation.

Available options:

Contextual GLM,

Gemini 2.5 Pro,

Gemini 2.5 Flash,

Gemini 2.0 Flash,

Gemini 2.0 Flash Lite,

Claude Opus 4,

Claude Sonnet 4,

GPT-5,

Default

agent_configs.generate_response_config.max_new_tokens

integer

The maximum number of tokens the model can generate in a response.

agent_configs.generate_response_config.temperature

number

The sampling temperature, which affects the randomness in the response.

agent_configs.generate_response_config.top_p

number

A parameter for nucleus sampling, an alternative to temperature which also affects the randomness of the response.

agent_configs.generate_response_config.frequency_penalty

number

This parameter adjusts how the model treats repeated tokens during text generation.

agent_configs.generate_response_config.seed

integer

This parameter controls the randomness of how the model selects the next tokens during text generation.

agent_configs.generate_response_config.calculate_groundedness

boolean

This parameter controls generation of groundedness scores.

agent_configs.generate_response_config.avoid_commentary

boolean

default:false

Flag to indicate whether the model should avoid providing additional commentary in responses. Commentary is conversational in nature and does not contain verifiable claims; therefore, commentary is not strictly grounded in available context. However, commentary may provide useful context which improves the helpfulness of responses.

agent_configs.global_config

Global Config · object

Parameters that affect the agent's overall RAG workflow

Show child attributes

agent_configs.global_config.enable_rerank

boolean

Enables reranking of retrieved chunks

agent_configs.global_config.enable_filter

boolean

Enables filtering of retrieved chunks with a separate LLM

agent_configs.global_config.enable_multi_turn

boolean

Enables multi-turn conversations. This feature is currently experimental and will be improved.

agent_configs.global_config.should_check_retrieval_need

boolean

Enables checking if retrieval is needed for the query. This feature is currently experimental and will be improved.

agent_configs.reformulation_config

Reformulation Config · object

Parameters that affect the agent's query reformulation

Show child attributes

agent_configs.reformulation_config.enable_query_expansion

boolean

Whether to enable query expansion.

agent_configs.reformulation_config.query_expansion_prompt

string

The prompt to use for query expansion.

agent_configs.reformulation_config.enable_query_decomposition

boolean

Whether to enable query decomposition.

agent_configs.reformulation_config.query_decomposition_prompt

string

The prompt to use for query decomposition.

agent_configs.translation_config

Translation Config · object

Parameters that affect the agent's translation workflow

Show child attributes

agent_configs.translation_config.translate_needed

boolean

Whether to enable translation for the agent's responses.

agent_configs.translation_config.translate_confidence

number

The confidence threshold for translation.

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

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.

/datastores

/datastores/{id}/documents

/agents

/contents

/agents/{id}/query

/lmunit

/users

/generate

/rerank

/parse

/workspaces

/billing

Authorizations

Body

Response