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

## 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.
  - `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.
    - `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-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/5298551c424b/schema)