> ## Documentation Index
> Fetch the complete documentation index at: https://guide.beenos-solutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API — Create, Update, and Chat with Agents

> REST API endpoints for creating, configuring, and chatting with AI agents in Beenos Solutions — including chat, conversation history, and agent updates.

The Agents API lets you create, configure, and interact with AI agents entirely through code. Each agent is connected to one or more knowledge bases and responds to user messages by retrieving relevant content and generating natural-language replies. Use these endpoints to build custom chat interfaces, integrate agents into your product, or automate agent configuration as part of your deployment pipeline.

***

### POST /v1/agents

Create a new AI agent and connect it to one or more knowledge bases. Once created, the agent is immediately available to receive chat messages.

#### Request Body

<ParamField body="name" type="string" required>
  A descriptive name for the agent. This name appears in the dashboard and in API responses.
</ParamField>

<ParamField body="knowledge_base_ids" type="array" required>
  An array of knowledge base IDs that this agent will search when generating replies. Provide at least one ID. For example: `["kb_abc123", "kb_def456"]`.
</ParamField>

<ParamField body="welcome_message" type="string">
  The message the agent sends when a user starts a new conversation session. Leave blank to skip an opening message.
</ParamField>

<ParamField body="fallback_message" type="string">
  The message the agent sends when it cannot find a relevant answer in the knowledge base. Defaults to a generic "I don't know" response if not set.
</ParamField>

<ParamField body="system_prompt" type="string">
  Persona and behavior instructions that shape how the agent responds. Use this to define tone, role, and any constraints you want to enforce.
</ParamField>

<ParamField body="response_length" type="string" default="medium">
  Controls the verbosity of agent replies. One of `short`, `medium`, or `detailed`.
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST https://api.beenossolutions.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "knowledge_base_ids": ["kb_abc123"],
    "welcome_message": "Hi! Ask me anything about our products.",
    "system_prompt": "You are a helpful support agent. Be concise and friendly.",
    "response_length": "medium"
  }'
```

#### Response

<ResponseField name="id" type="string">
  The unique identifier for this agent (for example, `agt_abc123`). Use this ID in all subsequent requests targeting this agent.
</ResponseField>

<ResponseField name="name" type="string">
  The name you assigned to the agent.
</ResponseField>

<ResponseField name="status" type="string">
  The agent's operational status. `active` agents accept chat messages. `inactive` agents are paused and will return a `403` response to chat requests.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp indicating when the agent was created.
</ResponseField>

```json theme={null}
{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

***

### GET /v1/agents/:id

Retrieve the full configuration and status of an existing agent.

#### Path Parameter

<ParamField path="id" type="string" required>
  The unique ID of the agent to retrieve (for example, `agt_abc123`).
</ParamField>

#### Example Request

```bash theme={null}
curl https://api.beenossolutions.com/v1/agents/agt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Response

<ResponseField name="id" type="string">
  The unique identifier for this agent (for example, `agt_abc123`).
</ResponseField>

<ResponseField name="name" type="string">
  The name assigned to this agent.
</ResponseField>

<ResponseField name="status" type="string">
  The agent's operational status: `active` or `inactive`.
</ResponseField>

<ResponseField name="knowledge_base_ids" type="array">
  The list of knowledge base IDs connected to this agent.
</ResponseField>

<ResponseField name="welcome_message" type="string">
  The message the agent sends at the start of a new conversation, if configured.
</ResponseField>

<ResponseField name="fallback_message" type="string">
  The message the agent sends when it cannot find a relevant answer in the knowledge base.
</ResponseField>

<ResponseField name="system_prompt" type="string">
  The persona and behavior instructions configured for this agent.
</ResponseField>

<ResponseField name="response_length" type="string">
  The configured verbosity setting for agent replies: `short`, `medium`, or `detailed`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp indicating when the agent was created.
</ResponseField>

```json theme={null}
{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "status": "active",
    "knowledge_base_ids": ["kb_abc123"],
    "welcome_message": "Hi! Ask me anything about our products.",
    "fallback_message": "I'm sorry, I don't have an answer for that.",
    "system_prompt": "You are a helpful support agent. Be concise and friendly.",
    "response_length": "medium",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

***

### PATCH /v1/agents/:id

Update the configuration of an existing agent. Send only the fields you want to change — all other fields remain unchanged. You can use this endpoint to rename an agent, swap its knowledge bases, update its system prompt, or change any other setting defined in `POST /v1/agents`.

#### Path Parameter

<ParamField path="id" type="string" required>
  The unique ID of the agent to update.
</ParamField>

#### Request Body

All fields are optional. Include only the fields you want to change — unspecified fields remain unchanged.

<ParamField body="name" type="string">
  A new descriptive name for the agent.
</ParamField>

<ParamField body="knowledge_base_ids" type="array">
  A replacement array of knowledge base IDs for the agent to search. This replaces the existing list entirely.
</ParamField>

<ParamField body="welcome_message" type="string">
  A new opening message for new conversation sessions.
</ParamField>

<ParamField body="fallback_message" type="string">
  A new fallback message to send when the agent cannot find a relevant answer.
</ParamField>

<ParamField body="system_prompt" type="string">
  Updated persona and behavior instructions for the agent.
</ParamField>

<ParamField body="response_length" type="string">
  Updated verbosity setting. One of `short`, `medium`, or `detailed`.
</ParamField>

#### Example Request

```bash theme={null}
curl -X PATCH https://api.beenossolutions.com/v1/agents/agt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "welcome_message": "Hello! How can I help you today?",
    "response_length": "detailed"
  }'
```

#### Response

Returns the full updated agent object. The response shape is identical to `GET /v1/agents/:id`.

<ResponseField name="id" type="string">
  The unique identifier for this agent.
</ResponseField>

<ResponseField name="name" type="string">
  The current name of the agent after the update.
</ResponseField>

<ResponseField name="status" type="string">
  The agent's current operational status: `active` or `inactive`.
</ResponseField>

<ResponseField name="knowledge_base_ids" type="array">
  The current list of knowledge base IDs connected to this agent.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp indicating when the agent was last updated.
</ResponseField>

```json theme={null}
{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "status": "active",
    "knowledge_base_ids": ["kb_abc123"],
    "welcome_message": "Hello! How can I help you today?",
    "fallback_message": "I'm sorry, I don't have an answer for that.",
    "system_prompt": "You are a helpful support agent. Be concise and friendly.",
    "response_length": "detailed",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T09:00:00Z"
  },
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2024-01-16T09:00:00Z"
  }
}
```

***

### POST /v1/agents/:id/chat

Send a message to an agent and receive a generated reply. The agent searches its connected knowledge bases for relevant content and returns a grounded response along with the source documents it used.

#### Path Parameter

<ParamField path="id" type="string" required>
  The unique ID of the agent to send the message to.
</ParamField>

#### Request Body

<ParamField body="message" type="string" required>
  The user's message or question. Plain natural language works best.
</ParamField>

<ParamField body="session_id" type="string">
  A unique identifier for the conversation session. Providing a consistent `session_id` across multiple turns enables the agent to maintain conversational context. We strongly recommend always supplying this value. If you omit it, each request is treated as a standalone, context-free message.
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST https://api.beenossolutions.com/v1/agents/agt_abc123/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the return policy?",
    "session_id": "user-session-42"
  }'
```

#### Response

<ResponseField name="reply" type="string">
  The agent's generated response to the user's message.
</ResponseField>

<ResponseField name="sources" type="array">
  The list of knowledge base source documents the agent used when generating its reply. Each item in the array contains:

  <Expandable title="Source object fields">
    <ResponseField name="id" type="string">
      The unique ID of the source document.
    </ResponseField>

    <ResponseField name="name" type="string">
      The human-readable name of the source document.
    </ResponseField>

    <ResponseField name="snippet" type="string">
      The specific text excerpt from the source that was most relevant to the query.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="session_id" type="string">
  The session identifier for this conversation turn. Matches the value you provided in the request, or a newly generated ID if you did not supply one.
</ResponseField>

<ResponseField name="confidence" type="number">
  A relevance score between `0.0` and `1.0` indicating how confident the agent is in its answer based on the retrieved content. Scores below `0.5` suggest the knowledge base may not contain enough information to answer the question well.
</ResponseField>

```json theme={null}
{
  "data": {
    "reply": "You can return any item within 30 days of purchase for a full refund...",
    "sources": [
      {
        "id": "src_xyz789",
        "name": "Return Policy",
        "snippet": "Items may be returned within 30 days of purchase..."
      }
    ],
    "session_id": "user-session-42",
    "confidence": 0.94
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-15T10:32:00Z"
  }
}
```

<Tip>
  Store the `session_id` on the client side and pass it with every subsequent message in the same conversation. This allows the agent to reference earlier messages, making multi-turn conversations significantly more coherent.
</Tip>

***

### GET /v1/agents/:id/conversations

List all conversation sessions for an agent, ordered by most recent activity. Use this endpoint to build conversation history views or audit chat logs.

#### Path Parameter

<ParamField path="id" type="string" required>
  The unique ID of the agent whose conversations you want to retrieve.
</ParamField>

#### Query Parameters

<ParamField query="limit" type="integer" default="20">
  The number of conversation sessions to return per page. Maximum `100`.
</ParamField>

<ParamField query="cursor" type="string">
  A pagination cursor from a previous response's `next_cursor` field.
</ParamField>

<ParamField query="session_id" type="string">
  Filter results to a specific conversation session by its ID.
</ParamField>

#### Example Request

```bash theme={null}
curl "https://api.beenossolutions.com/v1/agents/agt_abc123/conversations?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Response

<ResponseField name="data" type="array">
  A paginated array of conversation session objects, ordered by most recent activity first.

  <Expandable title="Conversation object fields">
    <ResponseField name="session_id" type="string">
      The unique identifier for this conversation session.
    </ResponseField>

    <ResponseField name="message_count" type="integer">
      The total number of messages exchanged in this session.
    </ResponseField>

    <ResponseField name="started_at" type="string">
      ISO 8601 timestamp indicating when the first message in this session was sent.
    </ResponseField>

    <ResponseField name="last_activity_at" type="string">
      ISO 8601 timestamp indicating when the most recent message in this session was sent.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string">
  A pagination cursor to pass as the `cursor` query parameter in your next request to retrieve the following page. Absent when you have reached the last page.
</ResponseField>

```json theme={null}
{
  "data": [
    {
      "session_id": "user-session-42",
      "message_count": 7,
      "started_at": "2024-01-15T10:30:00Z",
      "last_activity_at": "2024-01-15T10:45:00Z"
    },
    {
      "session_id": "user-session-41",
      "message_count": 3,
      "started_at": "2024-01-14T14:00:00Z",
      "last_activity_at": "2024-01-14T14:05:00Z"
    }
  ],
  "meta": {
    "request_id": "req_jkl012",
    "timestamp": "2024-01-15T11:00:00Z",
    "next_cursor": "cur_mno345"
  }
}
```