> For the complete documentation index, see [llms.txt](https://riteshs4hu.gitbook.io/infosec-notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://riteshs4hu.gitbook.io/infosec-notes/artificial-intelligence/ai-agents/agents-roles.md).
# Agents roles
When using chat-based models (like **DeepSeek-V3.1**), every message is part of a **conversation history**. Each message has a **role** that defines **who is speaking** and **the type of instruction it provides**.
#### Roles Overview
**1. system:** The **system prompt is not built into the LLM itself**.
* Purpose: Defines the **assistant’s behaviour/personality** for the entire conversation.
* Think of it as the *rules* or *stage directions* for the model.
* Placed **once at the start** (though you can change it mid-way if needed).
**2. user**
* Purpose: Represents **the human’s input/question**.
* This is what you type or send to the assistant.
**3. assistant**
* Purpose: Represents **the model’s past answers**.
* Usually filled in automatically after a response.
* Can also be pre-filled if you want to “seed” a conversation.
**Example 1 — System = Detailed Math Tutor**
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
json = '"task":"2+1"'
completion = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V3.1-Base:novita",
messages=[
{"role": "system", "content": "You are a very detailed math tutor."},
{"role": "user", "content": f"{json}"},
],
)
print(completion.choices[0].message)
```
**Result**
```
ChatCompletionMessage(
role='assistant',
content='',
reasoning_content="Let's solve the expression step by step:\n\n- We are adding two numbers: 2 and 1.\n- Start with 2, then add 1.\n- 2 + 1 = 3.\n\nSo, the result is **3**."
)
```
**Explanation:**
* Because the system role says *“detailed math tutor”*, the model gives a **step-by-step explanation**.
**Example 2 — System = Only Output JSON**
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
json = '"task":"2+1"'
completion = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V3.1-Base:novita",
messages=[
{"role": "system", "content": "You only reply with the final output in raw JSON formate"},
{"role": "user", "content": f"{json}"},
],
)
print(completion.choices[0].message)
```
**Result**
```
ChatCompletionMessage(
role='assistant',
content='',
reasoning_content='{"result": 3}'
)
```
**Explanation:**
* Because the system role said *“only reply in raw JSON”*, the assistant **skipped explanations** and returned just JSON.
***
**Summary Table of Roles**
| Role | Who? | Example Content | Purpose |
| ------------- | -------- | ---------------------------------- | -------------------------------------------------------------------- |
| **system** | Designer | `"You are a detailed math tutor."` | Sets the assistant’s style/personality/rules. |
| **user** | Human | `"task":"2+1"` | Asks a question / provides input. |
| **assistant** | Model | `"2+1 = 3"` | The AI’s reply. Can also be pre-filled to seed conversation history. |
#### Thinking vs Non-Thinking mode.
**Thinking Mode**
`...` The model **shows its reasoning process** step by step.
**Input:** `2+1=?` **Output (in reasoning\_content):**
```
Let's solve step by step:
- We have 2 and 1.
- Add them: 2 + 1 = 3.
So, the result is 3.
```
Use case: when you want the model to **explain how it got the answer**.
**Non-Thinking Mode**
The model **skips the reasoning** and just gives the final result.
**Input:** `2+1=?` **Output (in content):**
```
3
```
Use case: when you want **fast, short, direct answers**.
**In short:**
* **Thinking** = “Show work” (like a tutor).
* **Non-Thinking** = “Just the answer” (like a calculator).
***
#### Tool Call
A **tool call** is when the LLM is aware of **external tools/APIs** (like a calculator, search engine, or database) and decides when and how to call them during reasoning.
* Tools are **first-class entities**: the model can dynamically pick a tool to call.
* The model **acts as an orchestrator**:
* Reads your request
* Chooses a tool
* Sends/receives responses
* Returns the final answer to the user.
**Example: Tool Call**
```python
import os
import json
from openai import OpenAI
# --- Setup Client ---
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
# --- Define Calculator Function ---
def calculator(expression: str) -> float:
return eval(expression)
# --- Define Tool Schema ---
tools = [
{
"type": "function",
"function": {
"name": "calculator",
"description": "Evaluate a simple arithmetic expression",
"parameters": {
"type": "object",
"properties": {
"expression": {"type": "string"}
},
"required": ["expression"]
}
}
}
]
# --- Get User Input ---
user_input = input("Ask me something: ")
# --- Step 1: Send to LLM ---
resp1 = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V3.1:novita",
messages=[
{"role": "system", "content": "You are a tool-using assistant."},
{"role": "user", "content": user_input}
],
tools=tools
)
msg = resp1.choices[0].message
msg_dict = msg.model_dump()
# --- Step 2: If LLM calls a tool ---
tool_calls = msg_dict.get("tool_calls", [])
if tool_calls:
tool_call = tool_calls[0]
tool_name = tool_call.get("function", {}).get("name")
args_str = tool_call.get("function", {}).get("arguments", "{}")
args = json.loads(args_str)
# --- Step 3: Run Tool ---
tool_result = None
if tool_name == "calculator":
tool_result = calculator(args["expression"])
# --- Step 4: Send Tool Result Back ---
tool_call_id = tool_call.get("id", "tool_call_1")
resp2 = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V3.1:novita",
messages=[
{"role": "system", "content": "You are a tool-using assistant."},
{"role": "user", "content": user_input},
msg_dict,
{
"role": "tool",
"tool_call_id": tool_call_id,
"content": str(tool_result)
}
]
)
print("Answer:", resp2.choices[0].message.content)
else:
# If no tool call, just print the LLM's response
print("Answer:", msg.content)
```
**Agent** executes the calculator tool and feeds back the result to the LLM.
***
#### Free Chat APIs
*
*
*
***
#### Referance
*