Open in
Използвайте ThunderPhone като MCP сървър
Създавайте, тествайте, валидирайте и управлявайте гласови агенти на ThunderPhone от Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code или друг Streamable HTTP MCP клиент.
ThunderPhone предоставя HTTP сървър с поточно предаване за Протокола за контекст на модела на:
https://api.thunderphone.com/v1/mcpТова е обратната посока спрямо свързването на отдалечен MCP сървър с гласов агент:
| Посока | Резултат |
|---|---|
| Отдалечен MCP сървър → агент на ThunderPhone | Гласов агент може да извиква инструментите на отдалечения сървър. |
| ThunderPhone → вашият MCP клиент | Вашият агент за програмиране може да създава, тества и управлява ThunderPhone. |
Удостоверяване
Използвайте OAuth по подразбиране за клиенти от директорията: влезте, изберете организация и одобрете заявените разрешения. Прекъснете връзката от Настройки → Сигурност → Свързани приложения. Промяната или нулирането на паролата ви, както и промяната на имейла на акаунта ви, също отменят връзката, затова след това свържете клиента отново.
За клиенти, конфигурирани с API ключ, създайте ключ sk_live_ в Интеграции → API ключове и го предоставете на вашия MCP клиент като THUNDERPHONE_API_KEY. Ключът е обвързан с една организация; идентификатор, притежаван от друга организация, се третира като несъществуващ.
Организации, които обработват PHI
Ако обажданията на вашата организация може да съдържат защитена здравна информация (PHI),
защото имате BAA с ThunderPhone или вашите агенти са определени като
обработващи PHI, горният URL адрес никога не връща съдържание на обаждания: преписи,
записи, оценки, списъци с обаждания, експортирания, резултати от кампании, анализи на обаждания
и статистики, разговори, създадени от реални обаждания, и резултати от повторно възпроизвеждане. Тези инструменти връщат грешка с
code: "phi_content_unavailable". Създаването, тестването и конфигурирането на агенти
работи както обикновено.
Този URL адрес е посочен в публичните директории на асистенти, които не може да съдържат PHI. Ако вашата организация има собствен BAA с доставчика на асистента, обхващащ работното пространство, което използвате:
- Администратор на организацията отваря Организация → Общи → Достъп до AI асистент в ThunderPhone и потвърждава това покритие.
- Вместо това свържете асистента като персонализиран конектор с този URL адрес:
https://api.thunderphone.com/v1/mcp/baaТогава съдържанието на обажданията е налично там, включително обаждания, които може да съдържат PHI. Оттеглянето на потвърждението го спира при следващата заявка на асистента. Обаждане, което вашата организация е обработила като несъдържащо PHI, е налично и на двата URL адреса.
Алтернативи с CLI и stdio
CLI на ThunderPhone може да запише конфигурация на клиента, като запази несвързаните сървъри:
npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope userСлед глобална инсталация на @thunderphone/mcp използвайте thunderphone-mcp setup със
същите опции. Настройката поддържа Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop и Windsurf. Директният HTTP е предпочитан; Desktop използва stdio.
За всеки клиент, който поддържа stdio, конфигурирайте command: "npx" с
args: ["-y", "@thunderphone/mcp"]. Обвивката първо използва THUNDERPHONE_API_KEY,
след това идентификационните данни от thunderphone login, като обновява изтеклите токени,
а после OAuth чрез mcp-remote. Влизането от устройство и OAuth изискват съответното
внедряване на API OAuth. Пътят с API ключ не го изисква. Директните HTTP конфигурации не четат
хранилището за идентификационни данни на CLI; използвайте обвивката stdio, за да използвате повторно влизането от устройство.
Това са алтернативи на ръчните конфигурации на клиенти по-долу.
Конфигуриране на клиента
Claude и ChatGPT влизат чрез OAuth; не се използва API ключ. Ако все още нямате акаунт в ThunderPhone, изберете Създаване на акаунт на страницата за вход и след потвърждаване на имейла си ще се върнете към екрана за одобрение.
Claude (уеб, настолен компютър и мобилно устройство)
- Отворете Персонализиране → Конектори (Настройки → Конектори в по-стари версии). Ако ThunderPhone се показва в директорията с конектори, изберете го. В противен случай изберете Добавяне на персонализиран конектор, наименувайте го
ThunderPhoneи въведетеhttps://api.thunderphone.com/v1/mcp. - Изберете Свързване, влезте в ThunderPhone, изберете организацията и одобрете разрешенията.
- В чат активирайте ThunderPhone от менюто с инструменти и поискайте това, от което се нуждаете, например „Изброй моите агенти“.
Claude пита, преди да използва всеки инструмент за първи път. За да пропуснете повечето от тези подкани, отворете Персонализиране → Конектори → ThunderPhone и настройте Инструменти само за четене да бъдат винаги разрешени. Тези инструменти само извличат информация: агенти, обаждания, транскрипции, салда, документация. Оставете Инструменти за записване/изтриване с изискване за одобрение, ако искате да виждате всяка промяна, преди да се извърши.
Персонализираните конектори изискват платен план за Claude. При планове Team и Enterprise собственикът първо добавя конектора в настройките за конектори на организацията, след което всеки член свързва собствения си акаунт в ThunderPhone.
Какво е различното в Claude
Claude (конекторът и плъгинът Claude Code) получава по-ограничен набор от инструменти в съответствие с правилата на директорията за конектори на Claude:
- Всяко обаждане и текстово съобщение се потвърждават поотделно.
place_callиsend_smsпърво връщат предварителен преглед (агента, номерата „от“ и „до“, а за текстово съобщение — съобщението), както иconfirmation_token; нищо не се извършва или изпраща, докато Claude не повтори заявката с токена след вашето потвърждение. - Без управление на кампании.
create_campaign,add_campaign_contactsиcampaign_actionне са налични; създавайте, зареждайте и стартирайте кампании в таблото за управление.list_campaigns,get_campaign_statsиcheck_campaignпродължават да работят. - Без
test_integration. Тествайте заявката на интеграция от нейната страница в таблото за управление. preview_voiceвъзпроизвежда фиксиран примерен поздрав с избрания от вас глас и език; не произнася персонализиран текст.list_voicesиlist_agentsвръщат обобщение;get_agentсъдържа пълната конфигурация на агент.
Разкриване на използването на AI
Всяко обаждане, което агент на ThunderPhone извършва или приема, започва с устно разкриване на използването на AI. По подразбиране то гласи „Това обаждане е с AI асистент и ще бъде записано и транскрибирано.“ Изключването му (consent_announcement_enabled false или ai_live_processing_disclosure_override off) се отказва, освен ако администратор на организацията предварително не е записал подписана декларация в таблото за управление от който и да е клиент, включително Claude.
ChatGPT
- Ако ThunderPhone се показва в директорията с приложения на ChatGPT, изберете го и го свържете.
- В противен случай отворете Настройки → Приложения и конектори → Разширени настройки, включете Режим за разработчици и създайте конектор с URL адрес
https://api.thunderphone.com/v1/mcpи OAuth удостоверяване. - Влезте в ThunderPhone, изберете организацията и одобрете разрешенията. Добавете ThunderPhone към чат от менюто с инструменти.
Изтриването на агент или телефонен номер, отхвърлянето на чернова, стартирането на кампания и изпращането на тестова заявка, която може да записва във външна система, изискват второ потвърждение и в двете приложения; вижте Потвърждаване на разрушителни действия.
Claude Code
claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
--header "Authorization: Bearer $THUNDERPHONE_API_KEY"Codex
Добавете това към ~/.codex/config.toml:
[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"Cursor
Създайте .cursor/mcp.json:
{
"mcpServers": {
"thunderphone": {
"url": "https://api.thunderphone.com/v1/mcp",
"headers": {
"Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
}
}
}
}Claude Desktop
Добавете мост mcp-remote към конфигурацията на Claude Desktop:
{
"mcpServers": {
"thunderphone": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.thunderphone.com/v1/mcp",
"--header",
"Authorization: Bearer ${THUNDERPHONE_API_KEY}"
],
"env": {
"THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
}
}
}
}VS Code
Създайте .vscode/mcp.json и въведете ключа чрез подканата за въвеждане на VS Code:
{
"inputs": [
{
"type": "promptString",
"id": "thunderphone-api-key",
"description": "ThunderPhone organization API key",
"password": true
}
],
"servers": {
"thunderphone": {
"type": "http",
"url": "https://api.thunderphone.com/v1/mcp",
"headers": {
"Authorization": "Bearer ${input:thunderphone-api-key}"
}
}
}
}Инструменти
Всеки инструмент съдържа MCP анотации. В таблиците R означава само за четене, D — деструктивен, I — идемпотентен, а O — взаимодействие с външния свят/мрежата. Тире означава, че няма зададена подсказка.
Връзка
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
get_connection_identity | — | R, I | Валидира идентификационните данни и връща организацията и безопасни метаданни за идентификационните данни. |
Агенти
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_agents | — | R, I | Извежда списък с агенти. |
get_agent | agent_id | R, I | Получава един агент. |
create_agent | конфигурация на агент | — | Създава агент. Приема същите настройки като update_agent, включително steps, handoffs, intro_clip и intro_ring_count. |
update_agent | agent_id, променени полета, незадължителни prompt_edits, expected_prompt_sha256 | D | Подготвя полета в черновата на агента, като заменя съществуващите в черновата. Изпълнява се без стъпка за потвърждение: внедреният агент остава непроменен до deploy_agent, а discard_agent_draft връща черновата към предишното ѝ състояние. Можете също да зададете max_hold_seconds, system_tool_settings и words. За да промените част от подканата, изпратете prompt_edits (вижте Редактиране на подкана на място). |
deploy_agent | agent_id, незадължителен if_updated_at | D, I | Публикува черновата в продукционна среда. |
discard_agent_draft | agent_id, незадължителен if_updated_at, confirmation_token при втората заявка | D, I | Отхвърля подготвените промени. Изпълнява се в две стъпки, вижте Потвърждаване на разрушителни действия. |
duplicate_agent | agent_id, незадължително name | — | Копира агент в рамките на организацията. |
delete_agent | agent_id, confirmation_token при втората заявка | D, I | Изтрива окончателно агент. Изпълнява се в две стъпки. |
list_agent_versions | agent_id | R, I | Извежда списък с внедрените версии на конфигурацията. |
list_prompt_revisions | agent_id, незадължителни source, limit, offset | R, I | Извежда всяка промяна в текста на подканата на агента, включително черновите, всяка с разлика спрямо ревизията, която е заменила. Налично е, когато наборът инструменти за итерации на агенти е достъпен за вашата връзка (вижте по-долу). |
review_prompt | agent_id, незадължителни prompt, previous_prompt, quote_id, max_cost_cents | — | Преглежда черновата на подканата (или текста, който изпращате) спрямо ръководството за стил на подканите. За всяко откритие цитира откъса, посочва насоката и предлага редакция за търсене и замяна; резултатът също изброява поведенията, които подканата изисква, със стабилни идентификатори, дали е необходимо преструктуриране и, за собствената подкана на агента, дали тестовите му разговори трябва да бъдат обновени. Не променя нищо по агента; списъкът се запазва с ревизията на подканата му. Платено е, затова не е отбелязано като само за четене: първо поискайте оферта с dry_run, след това го изпълнете отново без dry_run, с върнатите от него quote_id и max_cost_cents. Тези платени изпълнения вече се отчитат към същия лимит на набора инструменти за организацията като останалите изпълнения на набора инструменти. Налично е, когато наборът инструменти за итерации на агенти е достъпен за вашата връзка (вижте по-долу). |
refactor_prompt | agent_id, незадължителни prompt, inventory, instructions, quote_id, max_cost_cents | — | Пренаписва подканата във формата от ръководството за стил и съпоставя всяко поведение като запазено, обединено, преформулирано или премахнато. Връща новия текст и разлика, като по подразбиране го прочита отново, за да отчете behavior_changes (добавени, премахнати или променени) и behavior_preserved; приложете го с update_agent. Платено: поискайте оферта с dry_run, след което го изпълнете веднъж с върнатите от него quote_id и max_cost_cents. Налично е, когато наборът инструменти за итерации на агенти е достъпен за вашата връзка (вижте по-долу). |
list_reusable_instructions | — | R, I | Извежда списък с повторно използваеми инструкции: споделени правила за подкани, свързани с много агенти чрез reusable_instruction_ids на update_agent. |
create_reusable_instruction | name, content | — | Създава несвързана повторно използваема инструкция. Само за администратори. |
Телефонни номера и оператори
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_phone_numbers | — | R, I | Извежда номерата и маршрутизирането на организацията. |
get_phone_number_limits | — | R, I | Получава използването и лимитите на управляваните номера. |
provision_phone_number | незадължителни area_code, city, state, idempotency_key | D, O | Закупува входящ номер, управляван от ThunderPhone. |
list_voip_connections | — | R, I | Извежда свързаните телекомуникационни доставчици на клиента. |
search_voip_numbers | connection_id, country, type, незадължителен area_code | R, I, O | Търси в наличностите на доставчика. |
import_voip_numbers | connection_id, numbers | D, O | Импортира номера, които вече са притежавани при доставчика. |
update_phone_number | phone_number_id, полета за маршрутизиране/етикет/webhook | D | Актуализира маршрутизирането на номера, включително назначаването на агент. |
delete_phone_number | phone_number_id, confirm, незадължителен release_at_provider, confirmation_token при втората заявка | D, I, O | Освобождава номер. В две стъпки. |
get_voip_setup_session | незадължителен session_id | R, I | Прочита водена настройка на доставчик (статус, контролен списък, въпроса, който очаква), или извежда отворените настройки. Настройката започва в таблото, защото изисква паролата за доставчика. Само за администратори. |
answer_voip_setup_question | session_id, question_id, answer | O | Предава отговора на потребителя към настройката. Пароли, съгласие за тестово обаждане, адресът на сървъра, потребителското име и разрешението ThunderPhone да влезе в акаунта при доставчика се попълват само в съветника за настройка; за тях връща връзката към съветника и не изпраща нищо. |
save_voip_setup | session_id, незадължителен name, confirmation_token при втората заявка | D, I, O | Запазва свързана чернова на връзка, за да може да се използва. В две стъпки. |
check_phone_number | phone_number или phone_number_id | R, I, O | Диагностицира един от собствените номера на организацията въз основа на данни: маршрутизиране, връзка, потвърждение, скорошни обаждания от доставчика и тестови обаждания, както и къде доставчикът го насочва. |
SMS
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
send_sms | from_number, to, body, idempotency_key | D, I, O | Изпраща едно SMS съобщение с обикновен текст чрез свързан номер на Twilio или Telnyx. |
Обаждания
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_calls | незадължителни филтри, limit, offset | R, I | Извежда обажданията с филтрите за REST хронология на обажданията, включително exclude_test_calls. |
get_call | call_id | R, I | Извлича статуса и метаданните на обаждането. |
get_call_transcript | call_id, незадължително live | R, I | Извлича транскрипцията на обаждането. |
get_call_audio_url | call_id, незадължително download | R, I, O | Връща подписан URL за аудио; никога не предава аудио поточно чрез MCP. |
get_call_grade | call_id | R, I | Извлича най-новата оценка на обаждането. |
place_call | agent_id, from_number, to_number | D, O | Извършва едно неизпълняващо се идемпотентно изходящо обаждане. |
export_calls | филтри за обаждания, export_format | R, I | Експортира до ограничението на REST крайна точка като JSON или CSV. |
get_call_analytics | незадължителни since_days, agent_id | R, I | Агрегира реалните обаждания по статус, посока, резултат, оценка и проблем, като тестовите обаждания се отчитат отделно. |
get_call_insights | call_ids (до 10) | R, I | Извлича едновременно оценката, резултата, обобщението и откритите проблеми на няколко обаждания. |
Тестване и валидиране
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_test_scenarios | agent_id | R, I | Извежда тестовите сценарии. |
create_test_scenario | agent_id, title, scenario_prompt, незадължителни условия | — | Създава сценарий. |
generate_test_scenarios | agent_id, незадължителни count, include_edge_cases, locale | O | Генерира сценарии от подканата на агента. |
run_agent_tests | agent_id, channel, consent_to_charge, незадължителен избор/матрица | D, O | Изпълнява сценарии чрез уеб или телефония. |
get_test_run | agent_id, batch_id | R, I | Получава състоянието на пакета и резултатите за всеки сценарий. |
test_my_agent | agent_id, consent_to_charge, незадължителни scenario_ids, count, wait_seconds | D, O | Тества агент с едно извикване: изпълнява запазените му сценарии (като генерира някои, когато няма такива) и изчаква до една минута за заключенията или връща batch_id за get_test_run. Таксува се като run_agent_tests. |
test_in_text | agent_id, callers (1 до 3 описания), незадължителни version, direction | O | Безплатен текстов тест: симулирани обаждащи се разговарят с черновата на агента (или с активната версия) чрез текст през реалния конвейер, а транскрипциите се връщат след около минута. Резултатите от инструмента са симулирани. |
run_simulation | agent_id, consent_to_charge, незадължителни scenario_prompt, direction, language | D, O | Стартира едно симулирано телефонно обаждане между AI обаждащ се и черновата на агента, за да може човек да чуе промяна. Връща изпълнението със състояние in_progress. Записва се, когато агентът записва обаждания, и се оценява след приключването му. Таксува се като тестово обаждане, първо от безплатния бюджет за тестове. |
get_simulation | simulation_id | R, I | Получава състоянието на симулирано обаждане и, след като приключи, създаденото от него: URL за запис с кратък срок на валидност и транскрипцията, когато агентът записва обаждания, както и оценката след приключване на оценяването (null преди това). |
list_validation_runs | agent_id | R, I | Извежда последните изпълнения за валидиране на черновата. |
get_validation_status | agent_id | R, I | Получава най-новото състояние на валидирането и съответствието на черновата. |
list_conversations | agent_id, незадължителни split, source | R, I | Извежда разговорите, спрямо които се тества агентът. Изисква набора от инструменти за итерация на агенти. |
get_conversation | conversation_id | R, I | Получава един тестов разговор с текущите му ходове. Изисква набора от инструменти за итерация на агенти. |
get_conversation_revisions | conversation_id, незадължителни limit, offset | R, I | Извежда всяка версия на тестов разговор: как и защо е променен (обновен за промяна в подканата, възстановен от по-ранна версия), добавените, премахнатите и променените поведения, преместените или оттеглените примери и разликите между редовете. Изисква набора от инструменти за итерация на агенти. |
generate_conversations | agent_id, незадължителни count, style | O | Създава симулирани тестови разговори спрямо черновата на агента и превръща най-трудните им моменти в примери за валидиране с ключове за отговорите. Първо поискайте оферта с dry_run; реално изпълнение изисква неговите quote_id и max_cost_cents. Изисква набора от инструменти за итерация на агенти. |
import_conversations | agent_id, незадължителни since_days, max_calls | O | Превръща последните обаждания на агента в тестови разговори (най-много по два на обаждащ се, като обажданията без запис се пропускат) и най-трудните им моменти в примери. Първо поискайте оферта с dry_run; реално изпълнение изисква неговите quote_id и max_cost_cents. Изисква набора от инструменти за итерация на агенти. |
refresh_conversations | agent_id, незадължителни conversation_ids, from_prompt_revision_id | O | Актуализира тестовите разговори на агента спрямо текущата му подкана, след като поведения са добавени, премахнати или променени: пренасочва, възстановява по-ранна версия (включително реално аудио) или пренаписва остарелите ходове и оттегля примери, чийто ход на обаждащия се вече липсва. Първо поискайте оферта с dry_run; реално изпълнение изисква неговите quote_id и max_cost_cents. Изисква набора от инструменти за итерация на агенти. |
get_conversation_job | job_id | R, I | Получава задача за генериране, импортиране или обновяване: състояние, натрупани разходи спрямо лимита и какво е създала или обновила. Изисква набора от инструменти за итерация на агенти. |
run_replays | agent_id, незадължителни overrides, split, engine, sample_size, sample_seed, max_cost_cents, quote_id, dry_run | D, O | Възпроизвежда извадка от примерите на агента с неговата чернова или със заместващи настройки като кандидат-подкана, глас или ниво и оценява всеки отговор спрямо ключа за отговор на примера. Точните възпроизвеждания изпълняват записаното аудио на хода, както би го изпълнило реално обаждане; процентите на успешно преминаване се отчитат за всеки механизъм. Възпроизвежданията на PHI обаждания се изпълняват като PHI, а конфигурация, която не могат да изпълнят (глас на ElevenLabs, експериментален продукт), се отказва. dry_run връща оценка, избрания sample_seed и quote_id; реално изпълнение изпраща същата заявка с този quote_id и sample_seed, както и max_cost_cents — твърд лимит: всяка заявка заделя горната си граница преди изпращане, а изпълнението спира, вместо да изпрати заявка, която не се побира, затова оставете резерв според largest_reservation_cents от оценката за всеки работник. Точно възпроизвеждане заделя най-лошия си случай — около 85 цента до $1.25 за всяко активно възпроизвеждане при типичен ход (две се изпълняват едновременно), при реална цена от няколко цента; изпълнението се таксува с действителната цена на възпроизвежданията, затова задайте max_cost_cents с резерв. Точното възпроизвеждане работи с бюджет, оразмерен за нормален ход плюс едно повторно изпълнение от вида, който се случва в продукционна среда (състезанието за отговор отново и повторен опит от наблюдател); ход, който изисква повече, се записва като грешка replay_budget_exhausted, отчита се отделно като budget_exhausted, изключва се от процента на успешно преминаване и при тестовия дял не изразходва кохорта. При тестовия дял кохорта със записано аудио на обаждащия се под конфигурация, различна от Bolt v2, се отказва (test_needs_exact_replay) и остава неизползвана: измерете тази конфигурация в дяла за разработка. Изисква набора от инструменти за итерация на агенти. |
compare_configs | agent_id, configs (2 до 4, първата е базовата), незадължителни sample_size, sample_seed, max_cost_cents, quote_id, dry_run | O | Възпроизвежда едни и същи примери при всяка конфигурация и отчита процента на успешно преминаване, примерите, поправени и счупени спрямо базовата конфигурация, закъснението до първото аудио, колко често обаждащият се е чакал потвърждение, сигнали или тишина, и цената на ход за всеки механизъм. Поискайте оферта с dry_run както при run_replays. Само за дела за разработка: при тестовия дял се отказва (comparison_dev_only); сравнете в дела за разработка, след което измерете избраното с run_replays. Изисква набора от инструменти за итерация на агенти. |
get_replay_run | run_id, незадължителен include_trace | R, I | Получава общите резултати, промените и резултатите за всеки пример от изпълнение на възпроизвеждане, както и неговата група за сравнение. Точните възпроизвеждания, които са изисквали повече от бюджета си, се отчитат отделно (budget_exhausted), извън процента на успешно преминаване. Изисква набора от инструменти за итерация на агенти. |
create_talk_link | agent_id, незадължителни variant_id, language, expires_in_minutes | O | Създава връзка за еднократна употреба, която човек отваря в браузър, за да разговаря с текущата чернова на агента, подобно на бутона „Разговор“ в таблото. Връзката изтича по подразбиране след 30 минути (най-много 120); разговорът се таксува като тестово обаждане „Разговор“. Вижте връзки за разговор. |
Инструментите, отбелязани като изискващи набора инструменти за итерация на агента, са част от него; наборът инструменти се активира за всяка организация, докато е в бета версия, а без него те връщат feature_not_enabled с указания какво да направите след това. Всеки разговор на агент е в неговия дял за разработка или в неговия тестов дял. Тестовият дял е за измерване на промяна, а не за нейното настройване, затова инструментите за разговори връщат разговор от тестовия дял само с неговите идентификатор, дял, източник, статус и броячи. Изпълнение на повторения в тестовия дял повтаря една цяла тестова кохорта (sample_size и sample_seed се игнорират), като изпълнява всеки пример с механизма, който данните му позволяват, определен преди изпълнението според примера (точен за записано аудио на обаждащия се, текстов за пример само с текст; конфигурация, различна от Bolt v2, няма точен път, така че кохорта със записано аудио се отказва за нея с test_needs_exact_replay и остава неизползвана; engine се пропуска или е auto, тъй като exact или text се отказват с test_engine_per_example и нищо не преминава към текстов режим), и връща само обобщени данни за всеки механизъм: процент на преминаване, неуспехи по сериозност и вид, забавяне и цена. Първият му резултат, който съхранява повторение, изразходва кохортата, така че следващото тестово изпълнение, за всяка подкана, взема друга, а когато не останат, се отказва с no_test_cohort (импортирането на обаждания или генерирането на разговори създава нови кохорти); изпълнение, което приключи преди да съхрани повторение (Core не може да повтори точно неговите аудио примери, exact_replay_unavailable, капацитетът му за повторения остава зает, core_busy, или всеки ход е изчерпал бюджета си, replay_budget_exhausted), оставя кохортата неизползвана. В дела за разработка точно повторение, което Core не може да изпълни, преминава към текстов режим и изпълнението се маркира като degraded. Сравненията се изпълняват само в дела за разработка. Всеки платен инструмент приема quote_id от своето пробно изпълнение, валиден за едно изпълнение: той се изразходва еднократно и трайно при стартиране на изпълнението, а старт, който бъде отказан или се провали преди това, го оставя използваем; изпълнение, което се провали след това, го посочва и се повтаря с ново пробно изпълнение за нов quote_id. С OAuth review_prompt и refactor_prompt изискват обхвата agents:write, включително за пробни изпълнения, а инструментите за разговори и повторения изискват testing:write, за да се изпълняват. Хората виждат целия тестов дял в таблото за управление. Обаждане, чийто обаждащ се е в тестовия дял на агент, е изключено, защото е част от тестовия набор. В организация с набора инструменти list_calls, get_call, get_call_transcript, get_call_audio_url, get_call_grade и export_calls го връщат точно като {"call_id", "start_time", "held_out": true} (started_at вместо start_time в редовете на експортиране), без неговите транскрипция, запис, история, оценка или отчет; всички останали полета на обаждането липсват, затова разчитайте изключен ред по неговото held_out преди всичко друго. REST API прави същото за API ключове и OAuth токени, а изгледите му за множество обаждания (обобщения на отчети, клъстери от проблеми, разследвания, отчети за конвейера) изключват изключените обаждания от своите броячи, клъстери и извадки и скриват всеки текст, който модел е написал от тях. Запис върху изключено обаждане (оценяване, повишаването му до тестов сценарий, повторно генериране на ход) се отказва с held_out_call. Тестов сценарий, който някой е повишил от изключено обаждане, се връща от list_test_scenarios и в тестовите изпълнения точно като {"id", "held_out": true}, а изпълнение на симулация от него, от get_test_run и инструментите за симулации, точно като {"id", "scenario_id", "held_out": true}; неговите симулирани обаждания също са изключени, а тестовите изпълнения все пак го изпълняват. Разговор за разработка, пример или резултат от повторение, копиран от обаждането на изключен обаждащ се (дяловете са за всеки агент, така че този обаждащ се може да е в тестовия дял на друг агент), се чете като такъв от тестовия дял. Хората виждат изключените обаждания изцяло в таблото за управление, а администратор може да позволи на един API ключ да ги вижда изцяло (include_held_out_calls, изключено по подразбиране, задава се само в таблото за управление) за интеграция, която се нуждае от всяко обаждане; MCP никога не го използва. Webhook-ите не са променени. Организациите без набора инструменти не виждат поле held_out и няма промяна.
generate_conversations, import_conversations и refresh_conversations изразходват кредити за модели. Първо ги извикайте с dry_run: true: отговорът е ценова оферта, стъпка по стъпка, с quote_id, и нищо не се изпълнява. Офертата отчита всяка заявка, която изпълнението може да направи при типичен размер. За реално изпълнение са нужни този quote_id (изтича след 15 минути и работи само със същите аргументи) и max_cost_cents, твърд лимит: преди всяка заявка задачата заделя максималната сума, която тя може да струва, и спира, вместо да изпрати заявка, която не се побира, като запазва написаното дотук. Поради това заделяне едно изпълнение може да спре с неизразходвана част от лимита си; largest_reservation_cents в офертата показва колко резерв да оставите. Симулираните обаждащи се се измислят от подсказката на агента; style: "adversarial" създава трудни обаждащи се, които поставят на изпитание слабите места на подсказката, и тези разговори винаги отиват в разделението за разработка. target: "changed_behaviors" насочва обаждащите се към промененото при последното редактиране на подсказката. За всеки агент се изпълнява по една от тези задачи или едно изпълнение на повторения наведнъж, така че опресняването никога не променя примерите, върху които се изпълнява повторение; стартиране, докато другото се изпълнява, връща job_active, replay_run_active или conversation_job_active с информация какво да изчакате.
След редактиране на подсказка, което добавя, премахва или променя поведение, review_prompt върху черновата на агента отчита колко тестови разговора са написани за подсказка с други поведения (conversations.refresh_suggested). След това refresh_conversations ги актуализира спрямо черновата, така че наборите за разработка и тестване да измерват новата подсказка върху истории, които тя би могла да произведе. Опресняването никога не губи нищо: всеки разговор запазва всяка предишна редакция, а когато премахнато правило се върне, се възстановява редакцията от времето, когато е съществувало, с реалното аудио на обаждащия се. Опресняване, стартирано от агент за програмиране, изключва от избора, офертата, напредъка и разхода разговорите от разделението за тестване и разговорите, копирани от изключени от извадката обаждания; посочването на такъв в conversation_ids връща 403 test_conversation. Човек ги опреснява от таблото за управление, а резултатите от тази задача ги показват на агентите за програмиране само като идентификатори и бройки. Пример с active, чиято история, отговор или ключ с верните отговори се пренаписва при опресняване, се връща в pending_review с етикет refreshed_needs_review. Офертата за опресняване калкулира цената на всеки разговор, който прочита, сякаш ще бъде пренаписан, и на всяко извикване на модел при неговия лимит за изход; тя важи за подсказката и разговорите, за които е издадена: ако някое от тях се промени преди изпълнението, поискайте нова оферта; ако подсказката се промени, докато задачата се изпълнява, тя спира като failed, като запазва опресненото дотук.
Знания
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_knowledge_bases | — | R, I | Извежда списък с бази знания. |
create_knowledge_base | name, незадължителен description | — | Създава база знания. |
add_knowledge_document | knowledge_base_id, name, content | — | Добавя текст или Markdown. |
import_knowledge_url | url, незадължителен name | O | Поставя публична страница на опашка за безопасно добавяне. |
search_knowledge | knowledge_base_id, query | R, I | Търси в извличането от продукционната среда. |
Интеграции, уебкуки и отдалечени MCP сървъри
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_integrations | — | R, I | Извежда интеграциите на HTTP функции. |
create_integration | display_name, spec на функцията, незадължителни полета за крайна точка | — | Създава HTTP инструмент. Добавете заглавки за удостоверяване в таблото за управление. |
test_integration | url, незадължителни метод/тяло/изчакване, integration_id с header_names, confirmation_token при втората заявка | D, O | Изпраща ограничена тестова заявка, защитена от SSRF. Запазените стойности на заглавките се попълват от интеграцията и се изпращат само до нейния собствен хост. POST (по подразбиране), PUT, PATCH и DELETE са в две стъпки; GET се изпълнява незабавно. |
list_webhook_endpoints | — | R, I | Извежда крайните точки за подписани уебкуки. |
list_webhook_deliveries | незадължителен agent_id, незадължителен endpoint_id | R, I | Извежда последните резултати от доставката на уебкуки без полезен товар. |
create_webhook_endpoint | label, url, незадължителни събития/статус | O | Създава крайна точка за подписан уебкук. |
copy_webhook_endpoint | endpoint_id, target_agent_id | I | Копира уебкука на агент, включително тайната за подписване, към друг агент на сървъра. Само за администратори. |
test_webhook_endpoint | endpoint_id | O | Изпраща синтетично събитие чрез обичайната доставка. |
list_mcp_servers | — | R, I | Извежда отдалечени сървъри, извикваеми от гласови агенти. |
create_mcp_server | display_name, url | O | Регистрира и синхронизира отдалечен сървър. Сървърите, които изискват заглавки за удостоверяване, се добавят в таблото за управление. |
sync_mcp_server_tools | server_id | D, O | Обновява каталога с инструменти на отдалечен сървър. |
Кампании
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_campaigns | — | R, I | Извежда изходящите кампании. |
create_campaign | полета на кампанията | — | Създава чернова на кампания. |
add_campaign_contacts | campaign_id, contacts | — | Добавя до 5 000 JSON контакта. |
campaign_action | campaign_id, action, незадължителни consent_to_charge, confirmation_token при втората заявка | D, O | Изпълнява start, pause, resume или stop. start и resume са в две стъпки; pause и stop се изпълняват незабавно. |
get_campaign_stats | campaign_id | R, I | Получава броячи и скорошни резултати. |
check_campaign | незадължителни campaign_id, contact_phone_number, contact_status | R, I | Обяснява защо дадена кампания не се обажда: прозореца ѝ за обаждания в собствената ѝ часова зона, контактите, за които е време да бъдат потърсени сега, и какво спира набирането. |
Настройки на организацията и блокирани обаждащи се
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
get_org_settings | — | R, I | Прочита часовата зона, работното време, тестовите номера, етикетите за резултати от обаждания, имената на статусите и кои известия са изключени, с updated_at. |
update_org_settings | променени настройки, if_updated_at, confirmation_token при поискване | D, I | Променя ги (само за администратори). Списъците и обектите заменят съхранената стойност. Изключването на известие или добавянето на тестов номер е в две стъпки. Резултатът съдържа старите стойности за отмяна. |
get_account_limits | — | R, I | Получава ограниченията на платформата със собствените стойности на тази организация. |
list_blocked_callers | незадължителни number, search | R, I | Извежда списък с блокираните номера на обаждащи се. |
block_callers | numbers, незадължителен note, confirmation_token при втората заявка | D, I | Отказва обаждания от тези номера, преди който и да е агент да отговори. В две стъпки, само за администратори. |
unblock_callers | numbers, confirmation_token при втората заявка | D, I | Премахва номера от списъка с блокирани. В две стъпки, само за администратори. |
get_org_settings, update_org_settings и get_account_limits изискват org:read или org:write OAuth обхват; при първо използване връзка, създадена преди да съществуват, ще поиска одобрение за него.
Възможности, помощ и импортирания
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
get_supported_languages | — | R, I | Извежда езиците, които агентите говорят, с кодове. |
get_agent_capabilities | — | R, I | Показва какво може да прави агент по време на обаждане и кои настройки и интеграции съществуват. |
escalate_to_human | summary | O | Иска помощ от екипа на ThunderPhone. Те отговарят в ThunderPhone. За организации, които може да обработват PHI, от ThunderPhone излиза само неутрална бележка. |
request_feature | title, request, details | O | Подавa заявка за функционалност към екипа на ThunderPhone. Най-много три на организация на ден. |
start_agent_import | platform | R, I | Връща връзката към таблото, където въвеждате своя ключ за Vapi, Retell, ElevenLabs или Bland и избирате агенти. Нито един инструмент не приема ключа. |
get_agent_import | незадължителен import_id | R, I | Извежда последните импортирания или статуса и съпоставените агенти на едно импортиране. |
commit_agent_import | import_id, незадължителни item_ids | O | Създава агентите от готово импортиране във фонов режим. Само за администратори. |
Гласове, таксуване и документация
| Инструмент | Основни аргументи | Анотации | Какво прави |
|---|---|---|---|
list_voices | — | R, I | Извежда списък с гласове и поддържани езици. |
preview_voice | voice, language, text | O | Генерира пример и връща подписан URL адрес. |
list_voice_clones | — | R, I | Извежда списък с персонализирани гласови клонинги. |
get_billing_summary | — | R, I | Извлича баланса и официалните цени на нивата; не са достъпни промени по плащанията. |
search_docs | query, незадължителен limit | R, I, O | Търси в индекса на публичната документация. |
get_doc_page | path | R, I, O | Извлича една публична страница с документация в Markdown. |
Резултатите за агент, обаждане, номер, кампания или настройка съдържат web_url — съответната страница в таблото, така че можете да я отворите в ThunderPhone или да продължите със Zeus там.
Всички продуктови инструменти използват същите REST кодови пътища като публичния API. Следователно REST валидирането, обхватът на организацията, ролите, допускането за фактуриране, квотите, потвърждението по TCPA, безопасността на доставчиците и поведението при одит се прилагат без промяна.
Редактиране на подкана на място
update_agent може да промени част от черновата на подканата, без да изпраща целия текст обратно. prompt_edits е подреден списък от двойки за намиране и замяна в същия формат, който връщат review_prompt и refactor_prompt:
{
"agent_id": 123,
"expected_prompt_sha256": "9c1f…",
"prompt_edits": [
{
"find": "Ask for their name and their phone number, then tell them we will call back.",
"replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
}
]
}Сървърът прилага редакциите по ред към текущата чернова на подканата на агента (разгърнатата подкана, когато няма чернова) и записва резултата в черновата по същия път като при update_agent с цяла подкана. Всеки find трябва да присъства точно веднъж в подканата във вида, в който е, когато дойде редът на съответната редакция. Ако това не е така, не се записва нищо и грешката посочва редакцията:
| Код | Значение | Какво да направите |
|---|---|---|
prompt_edit_not_found | Текстът find не е в текущата чернова на подканата. edit_index показва коя редакция. | Прочетете агента отново и копирайте пасажа точно. |
prompt_edit_ambiguous | Текстът find се среща повече от веднъж. occurrences показва колко пъти. | Включете повече от околния текст. |
stale_prompt | expected_prompt_sha256 не е SHA-256 на текущата чернова на подканата: тя се е променила, след като сте я прочели. | Прочетете агента отново, пренапишете промяната спрямо текущия текст и изпратете неговия SHA-256. |
conflict | Друг запис е извършен между прочитането на черновата от сървъра и записването ѝ. | Опитайте отново; черновата не е променена от това извикване. |
expected_prompt_sha256 не е задължителен и също защитава записването на цяла подкана. Използвайте prompt_sha256 от review_prompt или source_prompt_sha256 от refactor_prompt. Всяко извикване, което променя подканата, връща prompt_sha256 за новия текст, previous_prompt_sha256, когато сървърът първо е прочел черновата, и next_step, предлагаща review_prompt с previous_prompt, зададен на текста преди промяната. REST API приема само цялата подкана: PATCH /v1/agents/{agent_id} с prompt и if_updated_at.
Потвърждаване на разрушителни действия
Инструментите, отбелязани с D, променят или премахват нещо, или започват да набират реални хора. За тези, които не могат да бъдат отменени, са необходими две заявки. Първата заявка не променя нищо и връща:
{
"status": "confirmation_required",
"action": "Delete agent",
"target": { "id": 195, "name": "Front Desk Receptionist" },
"confirmation_token": "…",
"expires_in_seconds": 600,
"next_step": "…"
}Асистентът показва на потребителя какво ще бъде засегнато и иска потвърждение. След това повтаря заявката със същите аргументи плюс confirmation_token. Токенът е валиден 10 минути, работи еднократно (дори ако това извикване е неуспешно) и важи за една организация, едно лице, един инструмент и един точен набор от аргументи, така че изтриването на три агента изисква три потвърждения. campaign_action с pause или stop пропуска тази стъпка, за да може изпълнявана кампания винаги да бъде спряна веднага, както и test_integration с GET. Някои инструменти с D се изпълняват с една заявка, защото D обозначава ефекта им, а не потвърждение от страна на сървъра: update_agent заменя съдържанието на черновата (discard_agent_draft го възстановява), deploy_agent заменя продукционната конфигурация, update_phone_number пренасочва активни обаждания, sync_mcp_server_tools заменя каталога с инструменти на отдалечен сървър, import_voip_numbers пренасочва номерата към вашия оператор, run_agent_tests и run_simulation могат да изразходват кредит, send_sms и place_call достигат до реален човек (place_call запазва собственото си потвърждение за съгласие), а provision_phone_number купува номер. test_my_agent изразходва кредит за тестове и изисква consent_to_charge. run_replays също изразходва средства; неговата оценка от dry_run и ограничението max_cost_cents заместват потвърждението. Вашият MCP клиент все пак може да поиска да ги одобрите.
Някои промени, които могат да бъдат отменени, все пак изчакват потвърждение: винаги block_callers, unblock_callers и save_voip_setup; update_org_settings, когато деактивира предупреждение или добавя тестов номер; и update_agent, когато неговите attention_reasons деактивират едно от предупрежденията на агента. Техният next_step ви подканва да потвърдите точната промяна, вместо да предупреждава, че тя не може да бъде отменена.
Начални подкани
prompts/list предлага дванадесет многократно използваеми работни процеса:
create_inbound_receptionistrun_agent_testsbuy_and_attach_numberreview_low_grade_callsadd_url_to_agent_knowledgeimprove_agent_from_callscheck_change_before_deploytest_my_agentdiagnose_phone_numberwhy_campaign_not_callingcall_reportimport_agents
Използвайте prompts/get с името на посочената подкана и декларираните ѝ аргументи, за да получите готово за изпълнение потребителско съобщение.
Ресурси
resources/list предоставя публични кеширани справки:
| URI | Съдържание |
|---|---|
thunderphone://docs/llms.txt | Индекс на публичната документация. |
thunderphone://docs/quickstart | Markdown за бърз старт. |
thunderphone://pricing | Актуален Markdown с публичните цени. |
thunderphone://guides/prompt-style | Ръководството за стил на подканите за гласови агенти, спрямо което review_prompt извършва проверка. Идентификаторите на насоките му (P1, W2 и т.н.) са тези, които се цитират в констатациите. |
thunderphone://guides/working-with-thunderphone | Как асистентът трябва да работи с тези инструменти: малки итерации върху черновата, проверка преди всяко внедряване, потвърждение от потребителя за всичко, което е активно или се таксува, и никога да не иска тайни. |
Прочетете ресурс с resources/read. Публичните извличания използват кратко изчакване, ограничение от 2 MiB и десетминутен кеш в процеса.
Протокол и грешки
Сървърът поддържа версиите на протокола 2025-06-18 и 2025-03-26; връща поддържана версия на клиента, а в противен случай избира 2025-06-18. Той имплементира initialize, ping, инструменти, подкани, ресурси и известия. Известията връщат 202 Accepted. Този сървър без състояние не предоставя SSE слушател или изтриване на сесия, затова GET и DELETE връщат 405 Method Not Allowed с Allow: POST.
Неуспехите на инструменти остават успешни JSON-RPC отговори с isError: true. Текстът им съдържа кратко изречение, последвано от JSON блок:
{
"code": "insufficient_balance",
"detail": "There is not enough prepaid balance.",
"next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}Отличителният префикс outbound_tcpa_confirmation_required: се запазва за place_call. Непознатите JSON-RPC методи връщат -32601 в HTTP отговор 200. JSON-RPC пакетите не се поддържат от MCP 2025-06-18 и връщат коректна грешка за невалидна заявка -32600.