# Set system tools and call transfer > POST https://api.nabrah.ai/api/ext/agent/{agent_id}/system_tools Group: Agents. Page: https://www.nabrah.ai/en/docs/api-reference/agents/set-system-tools-and-call-transfer Sets the built-in system tools of the agent identified by `agent_id`, such as call transfer. The list you send replaces the agent's current system tools, so send every tool you want to keep; an empty list removes them all. The response returns the agent's system tools after the change. Authenticated with your API key. ## System tools Each entry has a `name`, an optional `when_to_use`, and a `config` for transfer. - **transfer**: Hands the call to a person. Needs a `config` (see below). Fields: `name`, `config`. - **convert_date_to_weekday**: Lets the agent work out the weekday of a date the caller mentions. - **get_phone_number, get_email_address, get_national_id**: Let the agent collect and confirm the caller's phone number, email address or national ID. - **when_to_use**: Up to 500 characters telling the agent when to use the tool, for example "When the caller asks for a sales person". Fields: `when_to_use`. ## Transfer config Phone calls only. - **transfer_to**: Where to transfer. A single number such as "+966500000000", a list of numbers (each a string or {"number": "+9665…", "hours": {…}}), or a category map such as {"Sales": {"desc": "when the caller wants to buy", "numbers": ["+9665…"]}}. `hours` uses days 1–7, start and end as HH:MM, and a timezone (default Asia/Riyadh). When several numbers are open, one is picked at random. Fields: `transfer_to`. - **transfer_type**: "warm": the agent calls the person and briefs them before connecting the caller. "cold": the caller is connected straight away. "forward": the call is handed back to the caller's phone system to transfer; on web calls it works like "cold". Fields: `transfer_type`. - **sip_outbound_number**: The outbound number used to place the transfer call. It must already be added to your project (GET /api/ext/sip_outbound); otherwise the request returns 404. Needed for warm and cold transfers, and for forward transfers on web calls. Fields: `sip_outbound_number`. Returns 404 when the agent does not exist in your project or the outbound number is not found. ## Authorization - `X-API-Key` (string, header, required): your workspace API key. ## Path parameters - `agent_id` (string, required) ## Body (application/json) ### Example: Transfer to one number Connect the caller to the front desk when they ask for a person. ```json { "system_tools": [ { "name": "transfer", "when_to_use": "When the caller asks to speak to a person", "config": { "transfer_to": "+966500000000", "transfer_type": "cold", "sip_outbound_number": "+966110000000" } } ] } ``` ### Example: Warm transfer by department Brief the right team before connecting, with Sales only during working hours. ```json { "system_tools": [ { "name": "transfer", "when_to_use": "When the caller needs a person", "config": { "transfer_to": { "Sales": { "desc": "the caller wants to buy or rent a unit", "numbers": [ { "number": "+966500000001", "hours": { "days": [ 1, 2, 3, 4, 7 ], "start": "09:00", "end": "17:00" } } ] }, "Support": { "desc": "the caller has a problem with a booking", "numbers": [ "+966500000002" ] } }, "transfer_type": "warm", "sip_outbound_number": "+966110000000" } }, { "name": "convert_date_to_weekday" } ] } ``` ### Example: Remove all system tools An empty list removes every system tool from the agent. ```json { "system_tools": [] } ``` ## Response ### 200 Successful Response Content type: `application/json` ```json { "system_tools": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "string", "config": {}, "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z", "when_to_use": "string" } ] } ``` ### 422 Validation Error Content type: `application/json` ```json { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } ``` ## Request examples ### cURL ```bash curl --request POST \ --url 'https://api.nabrah.ai/api/ext/agent//system_tools' \ --header 'X-API-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "system_tools": [ { "name": "transfer", "when_to_use": "When the caller asks to speak to a person", "config": { "transfer_to": "+966500000000", "transfer_type": "cold", "sip_outbound_number": "+966110000000" } } ] }' ``` ### Python ```python import requests url = "https://api.nabrah.ai/api/ext/agent//system_tools" headers = { "X-API-Key": "", } payload = { "system_tools": [ { "name": "transfer", "when_to_use": "When the caller asks to speak to a person", "config": { "transfer_to": "+966500000000", "transfer_type": "cold", "sip_outbound_number": "+966110000000" } } ] } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() print(response.json()) ``` ### JavaScript ```javascript const response = await fetch("https://api.nabrah.ai/api/ext/agent//system_tools", { method: "POST", headers: { "X-API-Key": "", "Content-Type": "application/json", }, body: JSON.stringify({ "system_tools": [ { "name": "transfer", "when_to_use": "When the caller asks to speak to a person", "config": { "transfer_to": "+966500000000", "transfer_type": "cold", "sip_outbound_number": "+966110000000" } } ] }), }); const data = await response.json(); console.log(data); ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { payload := strings.NewReader(`{ "system_tools": [ { "name": "transfer", "when_to_use": "When the caller asks to speak to a person", "config": { "transfer_to": "+966500000000", "transfer_type": "cold", "sip_outbound_number": "+966110000000" } } ] }`) req, _ := http.NewRequest("POST", "https://api.nabrah.ai/api/ext/agent//system_tools", payload) req.Header.Set("X-API-Key", "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(string(out)) } ```