# AI Agent

An AI Agent is the configuration of an assistant: the model it runs on, the instructions that shape its persona, the knowledge bases it may consult and the voice it speaks with.

Agents hold no conversation state. To talk to one, open an [AI Chat](https://docs.starkinfra.com/api/v2/ai-chat.md) that points at the agent and post [AI Messages](https://docs.starkinfra.com/api/v2/ai-message.md) to that chat.

Attach a `metadataSchema` to make the agent return structured data alongside every reply — an intent label, a sentiment score, an extracted order number — so your backend can act on the conversation without parsing prose.

### The AI Agent object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the AI Agent. |
| `name` | STRING | Name of the agent. Example: "Support Assistant". |
| `model` | STRING | AI model the agent runs on. Options: "bender-1.0", "prime-1.0". |
| `systemPrompt` | STRING | Instructions that define the agent's persona, tone and domain behavior. Empty string when none was set. |
| `voiceId` | STRING | Id of the AI Voice the agent speaks with. Empty string when the agent is text-only. |
| `knowledgeBaseIds` | LIST OF STRINGS | Ids of the AI Knowledge Bases the agent may consult before answering. |
| `metadataSchema` | OBJECT | Schema of the structured data the agent must extract on every reply. `null` when none was set. |
| `knowledgeBases` | LIST OF OBJECTS | Id and name of each attached knowledge base. Only returned when `expand=knowledgeBases` is sent. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create an AI Agent

`POST /v2/ai-agent`

Create a single agent. Only `name` and `model` are mandatory — an agent with no knowledge base, no voice and no schema is a plain chat assistant running on the default instructions.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Name of the agent. Between 1 and 100 characters. |
| `model` | REQUIRED | AI model the agent runs on. Options: `bender-1.0` for everyday conversations, `prime-1.0` for harder reasoning. |
| `systemPrompt` | OPTIONAL | Instructions that define the agent's persona, tone and domain behavior. Up to 100000 characters. Falls back to Stark Infra's default assistant prompt when omitted. |
| `voiceId` | OPTIONAL | Id of the AI Voice the agent speaks with. When set, every reply also carries a `speech` string ready to be sent to `POST /v2/ai-speech`. Omit it or send an empty string for a text-only agent. |
| `knowledgeBaseIds` | OPTIONAL | List of up to 100 AI Knowledge Base ids. Before answering, the agent retrieves the passages most relevant to the question from these bases. |
| `metadataSchema` | OPTIONAL | Flat object whose keys are the fields the agent must extract on every reply. Each field takes a `type` (`string`, `integer`, `number`, `boolean` or `array`), an optional `description` of up to 2000 characters, an optional `enum` of up to 20 strings for `string` fields, and a mandatory `items` element type for `array` fields. At most 20 fields and 8192 bytes. |

**Request**

```python
import starkinfra

agent = starkinfra.aiagent.create(
    starkinfra.AiAgent(
        name="Support Assistant",
        model="bender-1.0",
        system_prompt="You are the support assistant of an online store. Answer in the customer language, never invent policies and always offer the next practical step.",
        voice_id="5656565656565656",
        knowledge_base_ids=["6767676767676767"],
        metadata_schema={
            "intent": {
                "type": "string",
                "enum": ["order", "refund", "shipping", "other"],
                "description": "What the customer is trying to do."
            },
            "isEscalation": {
                "type": "boolean",
                "description": "Whether the conversation should be handed to a human."
            }
        }
    )
)

print(agent)
```

**Response**

```python
AiAgent(
    created=2022-01-01 00:00:00,
    id=4242424242424242,
    knowledge_base_ids=['6767676767676767'],
    knowledge_bases=None,
    metadata_schema={'intent': {'description': 'What the customer is trying to do.', 'enum': ['order', 'refund', 'shipping', 'other'], 'type': 'string'}, 'isEscalation': {'description': 'Whether the conversation should be handed to a human.', 'type': 'boolean'}},
    model=bender-1.0,
    name=Support Assistant,
    system_prompt=You are the support assistant of an online store. Answer in the customer language, never invent policies and always offer the next practical step.,
    updated=2022-01-01 00:00:00,
    voice_id=5656565656565656
)
```

### List AI Agents

`GET /v2/ai-agent`

Get the agents in your workspace, newest first, in chunks of at most 100.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `knowledgeBases`. When `fields` is also sent, the expanded attribute must be listed there too. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results, returned by the previous call. |

**Request**

```python
import starkinfra

agents = starkinfra.aiagent.query(expand=["knowledge_bases"])

for agent in agents:
    print(agent)
```

**Response**

```python
AiAgent(
    created=2022-01-01 00:00:00,
    id=4242424242424242,
    knowledge_base_ids=['6767676767676767'],
    knowledge_bases=[AiKnowledgeBase[6767676767676767]],
    metadata_schema=None,
    model=bender-1.0,
    name=Support Assistant,
    system_prompt=,
    updated=2022-01-01 00:00:00,
    voice_id=5656565656565656
)
```

### Get an AI Agent

`GET /v2/ai-agent/:id`

Get a single agent by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the agent entity. |
| `fields` | OPTIONAL | Comma-separated list of attributes to keep in the response JSON. |
| `expand` | OPTIONAL | Comma-separated list of extra attributes to compute. Options: `knowledgeBases`. |

**Request**

```python
import starkinfra

agent = starkinfra.aiagent.get("4242424242424242")

print(agent)
```

**Response**

```python
AiAgent(
    created=2022-01-01 00:00:00,
    id=4242424242424242,
    knowledge_base_ids=['6767676767676767'],
    knowledge_bases=None,
    metadata_schema=None,
    model=bender-1.0,
    name=Support Assistant,
    system_prompt=,
    updated=2022-01-01 00:00:00,
    voice_id=5656565656565656
)
```

### Update an AI Agent

`PATCH /v2/ai-agent/:id`

Change an agent's configuration. Chats already pointing at the agent pick up the new configuration on their next message.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the agent entity. |
| `name` | OPTIONAL | New name for the agent. Between 1 and 100 characters. |
| `model` | OPTIONAL | New AI model. Options: `bender-1.0`, `prime-1.0`. |
| `systemPrompt` | OPTIONAL | New instructions for the agent. Up to 100000 characters. Send an empty string to remove them. |
| `voiceId` | OPTIONAL | New AI Voice id. Send an empty string to make the agent text-only. |
| `knowledgeBaseIds` | OPTIONAL | List of AI Knowledge Base ids the agent should end up with. Replaces the current list. Omit it to keep the current list, or send an empty list to detach every knowledge base. |
| `metadataSchema` | OPTIONAL | New schema of the structured data the agent must extract. |

**Request**

```python
import starkinfra

agent = starkinfra.aiagent.update(
    "4242424242424242",
    model="prime-1.0",
    knowledge_base_ids=["6767676767676767", "7878787878787878"]
)

print(agent)
```

**Response**

```python
AiAgent(
    created=2022-01-01 00:00:00,
    id=4242424242424242,
    knowledge_base_ids=['6767676767676767', '7878787878787878'],
    knowledge_bases=None,
    metadata_schema=None,
    model=prime-1.0,
    name=Support Assistant,
    system_prompt=,
    updated=2022-01-02 00:00:00,
    voice_id=5656565656565656
)
```

### Delete AI Agents

`DELETE /v2/ai-agent`

Delete up to 100 agents at once. The ids travel in the query string, not in the body.

Deleting an agent does not delete the chats that used it, but those chats can no longer receive new messages.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `ids` | REQUIRED | Comma-separated list of agent ids to delete. Between 1 and 100 ids. |

**Request**

```python
import starkinfra

agents = starkinfra.aiagent.delete(ids=["4242424242424242"])

for agent in agents:
    print(agent)
```

**Response**

```python
AiAgent(
    created=2022-01-01 00:00:00,
    id=4242424242424242,
    knowledge_base_ids=['6767676767676767'],
    knowledge_bases=None,
    metadata_schema=None,
    model=bender-1.0,
    name=Support Assistant,
    system_prompt=,
    updated=2022-01-02 00:00:00,
    voice_id=5656565656565656
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/ai-agent-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ai-agent-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ai-agent-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ai-agent-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ai-agent-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ai-agent-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ai-agent-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ai-agent-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ai-agent-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ai-agent-curl.md)