---
title: "Create Agent"
method: POST
path: "/agents"
tags: ["/agents"]
---

# Create Agent

`POST /agents`

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

## Request body

- CreateAgentRequest — Input to Create Agent request
  - `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.
  - `filter_prompt` string — The prompt to an LLM which determines whether retrieved chunks are relevant to a given query and filters out irrelevant chunks.
  - `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` AgentConfigs — Response to configs for different components
    - `retrieval_config` RetrievalConfig — Captures Retrieval configurations for an Agent
      - `top_k_retrieved_chunks` integer — The maximum number of retrieved chunks from the datastore.
      - `lexical_alpha` number — The weight of lexical search during retrieval
      - `semantic_alpha` number — The weight of semantic search during retrieval
    - `filter_and_rerank_config` FilterAndRerankConfig — Captures Filter and Rerank configurations for an Agent
      - `top_k_reranked_chunks` integer — The number of highest ranked chunks after reranking to be used
    - `generate_response_config` GenerateResponseConfig — Captures advance LLM configurations for an Agent
      - `max_new_tokens` integer — The maximum number of tokens the model can generate in a response.
      - `temperature` number — The sampling temperature, which affects the randomness in the response.
      - `top_p` number — A parameter for nucleus sampling, an alternative to `temperature` which also affects the randomness of the response.
      - `frequency_penalty` number — This parameter adjusts how the model treats repeated tokens during text generation.
      - `seed` integer — This parameter controls the randomness of how the model selects the next tokens during text generation.
      - `calculate_groundedness` boolean — This parameter controls generation of groundedness scores.
    - `global_config` GlobalConfig — Captures global configs
      - `enable_rerank` boolean — Enables reranking of retrieved chunks
      - `enable_filter` boolean — Enables filtering of retrieved chunks with a separate LLM
      - `enable_multi_turn` boolean — Enables multi-turn conversations. This feature is currently experimental and will be improved.
  - `name` string, required — Name of the agent
  - `description` string — Description of the agent
  - `datastore_ids` string[] — The IDs of the datastore to associate with this agent.

## Response `200`

Successful Response

- CreateAgentOutput — Response to POST /agents request
  - `id` string, uuid, 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.

## Other responses

- `422` — Validation Error

## Changes

- **2025-03-11** `194878b194cd` — 2 info
  - added the new optional request property `agent_configs/generate_response_config/calculate_groundedness`
  - added the new optional request property `filter_prompt`
- **2025-02-26** `5298551c424b` — 1 breaking, 1 info
  - the `system_prompt` request property's maxLength was decreased to `8000`
  - added the new optional request property `agent_configs`
- **2025-01-14** `4dd01a1cc34b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/contextualai/apis/endpoints/changes/agents/post.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) · [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/contextualai/endpoints/revisions/194878b194cd/schema)