Agent gateway
Документація agent gateway
Agent gateway - окремий домен agents.jobsai.cz. Клієнти реєструються на головному сайті, потім отримують DPoP-прив'язаний OAuth2 токен через client-credentials.
Як працює agent gateway
- Розробник заповнює реєстрацію і підтверджує електронну пошту.
- Розробник під час реєстрації вказує публічний DPoP-ключ (JWK або JWKS URL). Після підтвердження e-mail система одноразово показує client_id і client_secret.
- Агент запитує токен на agents.jobsai.cz/v1/oauth/token з DPoP-доказом.
- MCP/A2A/ACP ендпоінти перевіряють DPoP-прив'язку токена та окрему згоду кандидата, а для інструментів компаній доручення компанії.
DPoP: claim htu має дорівнювати точній URL запиту. Nonce необов'язкова - пропустіть її або використайте останнє значення з заголовка відповіді DPoP-Nonce (самостійно згенерована nonce буде відхилена). Авторитетний токен-ендпоінт вказано в OAuth метаданих.
Ідемпотентність: кожна операція запису (MCP submit_application, withdraw_application, propose_action і execute_approved_action, інструменти компаній create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job і confirm_job_open, ACP POST /runs і /runs/:id/cancel) вимагає заголовка Idempotency-Key (UUID або токен 8-255 символів [a-zA-Z0-9_-]). Без нього API повертає 400 idempotency_key_required. Стрімінгові інструменти (subscribe, stream_matches) через tools/call повертають лише вказівник - сам потік відкрийте другим запитом з Accept: text/event-stream.
Quickstart: підключіть MCP-клієнт
Від нуля до першого виклику за 3 кроки. Сервер працює на agents.jobsai.cz (streamable HTTP); інструменти читання потребують зареєстрованого агента, запис - додатково конверта згоди кандидата, а інструменти компаній - доручення компанії.
1. Зареєструйте агента
Сторінка реєстрації агента видає client_id і client_secret (показуються один раз). Токени видає OAuth 2.1 client credentials flow з discovery за RFC 8414 (посилання нижче).
2. Додайте сервер у клієнт
Claude Desktop і сумісні клієнти: додайте до конфігурації mcpServers:
{
"mcpServers": {
"jobsai": {
"type": "http",
"url": "https://agents.jobsai.cz/v1/mcp"
}
}
}Claude Code (CLI):
claude mcp add --transport http jobsai https://agents.jobsai.cz/v1/mcp3. Зробіть перший виклик
Після підключення клієнт завантажує tools/list. Почніть із search_jobs (пошук актуальних вакансій) і get_job (деталі). Інструменти запису потребують конверта згоди - кандидат надає його в розділі Агентний доступ свого акаунта. Інструменти компаній потребують доручення компанії - його видає власник або адміністратор на сторінці ШІ-агенти в акаунті компанії.
Огляд інструментів
| Інструмент | Необхідний доступ |
|---|---|
| search_jobs | jobs:read |
| get_job | jobs:read |
| submit_application | applications:write + consent envelope |
| get_application_status | applications:read + consent envelope |
| list_applications | applications:read + consent envelope |
| withdraw_application | applications:write + consent envelope |
| saved_jobs | applications:read/write + consent envelope |
| subscribe (SSE) | applications:read + consent envelope |
| stream_matches (SSE) | matches:read + consent envelope |
| propose_action | scope of the proposed action + consent envelope |
| get_action_proposal | scope of the proposed action + consent envelope |
| execute_approved_action | scope of the proposed action + consent envelope |
| list_employer_jobs | employer_jobs:read + representation envelope |
| get_employer_job | employer_jobs:read + representation envelope |
| list_employer_branches | employer_jobs:read + representation envelope |
| create_job_draft | employer_jobs:write + representation envelope |
| update_job | employer_jobs:write (live job: employer_jobs:publish) + representation envelope |
| update_job_terms | employer_jobs:write (live job: employer_jobs:publish) + representation envelope |
| confirm_job_terms | employer_jobs:write (live job: employer_jobs:publish) + representation envelope |
| publish_job | employer_jobs:publish + representation envelope |
| archive_job | employer_jobs:publish + representation envelope |
| confirm_job_open | employer_jobs:publish + representation envelope |
У tools/list кожен інструмент має анотації MCP: readOnlyHint для інструментів, які лише читають, destructiveHint для інструментів, які можуть щось видалити, відкликати, скасувати, приховати або перезаписати, та idempotentHint там, де повторний виклик нічого більше не змінює. Клієнт за ними визначає, коли запитати користувача; доступ і далі перевіряє сервер.
Дії, які підтверджує кандидат
Інструменти propose_action, get_action_proposal і execute_approved_action утворюють цикл підтвердження. Агент лише пропонує дію; кандидат бачить точний текст команди у своєму обліковому записі JobsAI (агентний доступ, розділ підтверджень), може змінити її та підтвердити, і лише після цього агент виконує саме цю команду, один раз. Довгострокова згода не замінює це підтвердження. Потрібний scope - це scope запропонованої дії, і він має бути і в токені, і в згоді. Функція доступна лише там, де оператор її увімкнув; в інших середовищах інструменти повертають approvals_unavailable.
Агент компанії
Інструменти list_employer_jobs, get_employer_job, list_employer_branches, create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job і confirm_job_open керують вакансіями однієї компанії. Агент викликає їх із дорученням (representation envelope), яке видає власник або адміністратор компанії на сторінці ШІ-агенти в акаунті компанії, і надсилає його з кожним викликом у заголовку X-Jobsai-Representation-Envelope поруч із DPoP-токеном. Потрібний scope (employer_jobs:read, employer_jobs:write або employer_jobs:publish) має бути і в токені, і в дорученні. Агент діє як людина, яка видала доручення. Доручення діє 7, 30 або 90 днів, і компанія може будь-коли його відкликати.
- Чернетки (employer_jobs:read + employer_jobs:write): читання вакансій і робочих місць компанії, створення й редагування чернеток вакансій та їхніх умов. Публікує людина з компанії.
- Чернетки та публікація (додатково employer_jobs:publish): публікація, редагування опублікованих вакансій, архівування та підтвердження, що позиція досі відкрита.
Опублікувати можна лише вакансію перевіреної компанії з діапазоном зарплати. Тексти проходять антидискримінаційну перевірку, і агент не може скористатися винятком. Кожен виклик записується в журнал активності, який бачить компанія. Без доручення інструменти повертають representation_required, після відкликання representation_revoked. Зміни захищає оптимістичне блокування: update_job потребує editHash, а update_job_terms потребує terms.revision з get_employer_job; застаріле значення повертає facts_changed (reason stale_edit_hash або stale_terms_revision). Зміна назви чи опису підвищує terms.revision і скасовує підтвердження умов, тому перед наступною зміною умов завантажте вакансію знову.
Довідка для компаній: ШІ-агенти для компаній
Приклади промптів
- Find 5 open cook positions in Prague on JobsAI and compare their salary ranges.
- Get the details of JobsAI job <id> and summarize the requirements in Czech.
- With my JobsAI consent envelope, apply to job <id> and then check the application status.
- With our company's JobsAI representation envelope, create a draft job for a warehouse worker in Brno with a salary range of 32000-38000 CZK per month.
- List our company's active JobsAI jobs and confirm the ones that are still open.
Сервер також є в офіційному MCP registry під іменем cz.jobsai/jobsai.
Посилання
- MCP server (Streamable HTTP)
- OAuth metadata (RFC 8414)
- OAuth protected resource (RFC 9728)
- JWKS
- A2A agent card (transport discovery)
- ACP manifest (agent.json)
- ACP OpenAPI
- Discovery index (MCP + A2A + ACP)
- Машиночитний compliance.json
Машиночитний огляд відповідності (постачальник, категорія ризику, людський нагляд, контакт і права суб'єкта даних) доступний за адресою /compliance.json.
Scope messages:write зарезервований для майбутнього ендпоінту повідомлень і наразі не видається в токенах.