Agent gateway

Dokumenty pre agent gateway

Agent gateway je oddelenou plochou na doméne agents.jobsai.cz. Klienti sa registrujú na hlavnom webe, potom získajú DPoP-viazaný OAuth2 token cez client-credentials.

Ako funguje agent gateway

  1. Vývojár vyplní registráciu a potvrdí e-mail.
  2. Vývojár pri registrácii uvedie verejný DPoP kľúč (JWK alebo JWKS URL). Po potvrdení e-mailu systém jednorazovo zobrazí client_id a client_secret.
  3. Agent požiada o token na agents.jobsai.cz/v1/oauth/token s DPoP dôkazom.
  4. MCP/A2A/ACP endpointy overia DPoP väzbu tokenu a samostatný súhlas kandidáta, pri nástrojoch pre firmy poverenie firmy.

DPoP: claim htu musí zodpovedať presnej URL požiadavky. Nonce je voliteľná - buď ju vynechajte, alebo použite poslednú hodnotu z response hlavičky DPoP-Nonce (vlastná vygenerovaná nonce bude odmietnutá). Autoritatívny token endpoint nájdete v OAuth metadátach.

Idempotencia: každá zapisovacia operácia (MCP submit_application, withdraw_application, propose_action a execute_approved_action, nástroje pre firmy create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job a confirm_job_open, ACP POST /runs a /runs/:id/cancel) vyžaduje hlavičku Idempotency-Key (UUID alebo token 8-255 znakov [a-zA-Z0-9_-]). Bez nej API vracia 400 idempotency_key_required. Streamovacie nástroje (subscribe, stream_matches) vracajú cez tools/call len ukazovateľ - samotný stream otvoríte druhou požiadavkou s Accept: text/event-stream.

Quickstart: pripojte MCP klienta

Od nuly k prvému volaniu v 3 krokoch. Server beží na agents.jobsai.cz (streamable HTTP); čítacie nástroje vyžadujú registrovaného agenta, zápisy navyše súhlasovú obálku kandidáta a nástroje pre firmy poverenie firmy.

1. Zaregistrujte agenta

Na stránke registrácie agenta získate client_id a client_secret (zobrazí sa len raz). Tokeny vydáva OAuth 2.1 client credentials flow s discovery podľa RFC 8414 (odkazy nižšie).

2. Pridajte server do klienta

Claude Desktop a kompatibilní klienti: pridajte do konfigurácie 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/mcp

3. Zavolajte prvý nástroj

Po pripojení klient načíta tools/list. Začnite so search_jobs (vyhľadávanie živých ponúk) a get_job (detail). Zápisové nástroje vyžadujú súhlasovú obálku - kandidát ju udelí v sekcii Agentný prístup vo svojom účte. Nástroje pre firmy vyžadujú poverenie firmy - vydá ho vlastník alebo správca na stránke AI agenti v účte firmy.

Prehľad nástrojov

NástrojOprávnenie
search_jobsjobs:read
get_jobjobs:read
submit_applicationapplications:write + consent envelope
get_application_statusapplications:read + consent envelope
list_applicationsapplications:read + consent envelope
withdraw_applicationapplications:write + consent envelope
saved_jobsapplications:read/write + consent envelope
subscribe (SSE)applications:read + consent envelope
stream_matches (SSE)matches:read + consent envelope
propose_actionscope of the proposed action + consent envelope
get_action_proposalscope of the proposed action + consent envelope
execute_approved_actionscope of the proposed action + consent envelope
list_employer_jobsemployer_jobs:read + representation envelope
get_employer_jobemployer_jobs:read + representation envelope
list_employer_branchesemployer_jobs:read + representation envelope
create_job_draftemployer_jobs:write + representation envelope
update_jobemployer_jobs:write (live job: employer_jobs:publish) + representation envelope
update_job_termsemployer_jobs:write (live job: employer_jobs:publish) + representation envelope
confirm_job_termsemployer_jobs:write (live job: employer_jobs:publish) + representation envelope
publish_jobemployer_jobs:publish + representation envelope
archive_jobemployer_jobs:publish + representation envelope
confirm_job_openemployer_jobs:publish + representation envelope

V tools/list má každý nástroj MCP anotácie: readOnlyHint pri nástrojoch, ktoré len čítajú, destructiveHint pri nástrojoch, ktoré môžu niečo odobrať, stiahnuť, zrušiť, skryť alebo prepísať, a idempotentHint tam, kde opakované volanie nič ďalšie nezmení. Klient podľa nich spozná, kedy sa má opýtať používateľa; oprávnenia ďalej overuje server.

Akcie, ktoré potvrdzuje kandidát

Nástroje propose_action, get_action_proposal a execute_approved_action tvoria schvaľovaciu slučku. Agent akciu iba navrhne, kandidát vidí presné znenie príkazu vo svojom účte na JobsAI (agentný prístup, sekcia schválenia), môže ho upraviť a potvrdiť; až potom agent vykoná práve tento príkaz, a to raz. Dlhodobá súhlasová obálka toto potvrdenie nenahrádza. Požadovaný scope je scope navrhovanej akcie a musí byť v tokene aj v obálke. Funkcia je dostupná len v prostrediach, kde ju prevádzkovateľ zapol; inde nástroje vracajú approvals_unavailable.

Agent firmy

Nástroje list_employer_jobs, get_employer_job, list_employer_branches, create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job a confirm_job_open spravujú ponuky jednej firmy. Agent ich volá s poverením (representation envelope), ktoré vydá vlastník alebo správca firmy na stránke AI agenti v účte firmy, a posiela ho pri každom volaní v hlavičke X-Jobsai-Representation-Envelope vedľa DPoP tokenu. Potrebný scope (employer_jobs:read, employer_jobs:write alebo employer_jobs:publish) musí byť v tokene aj v poverení. Agent koná ako osoba, ktorá poverenie vydala. Poverenie platí 7, 30 alebo 90 dní a firma ho môže kedykoľvek odvolať.

  • Koncepty (employer_jobs:read + employer_jobs:write): čítanie ponúk a pracovísk firmy, zakladanie a úprava konceptov ponúk a ich podmienok. Zverejňuje človek z firmy.
  • Koncepty aj zverejňovanie (navyše employer_jobs:publish): zverejnenie, úprava zverejnených ponúk, archivácia a potvrdenie, že je pozícia stále otvorená.

Zverejniť možno len ponuku overenej firmy s mzdovým rozpätím. Texty prechádzajú antidiskriminačnou kontrolou a agent si nemôže uplatniť výnimku. Každé volanie sa zapisuje do logu činnosti, ktorý firma vidí. Bez poverenia vracajú nástroje representation_required, po odvolaní representation_revoked. Zmeny stráži optimistický zámok: update_job potrebuje editHash a update_job_terms terms.revision z get_employer_job; zastaraná hodnota vracia facts_changed (reason stale_edit_hash alebo stale_terms_revision). Zmena názvu alebo popisu zvýši terms.revision a zruší potvrdenie podmienok, preto ponuku pred ďalšou úpravou podmienok načítajte znova.

Pomocník pre firmy: AI agenti pre firmy

Ukážkové prompty

  • 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.

Server nájdete aj v oficiálnom MCP registry pod menom cz.jobsai/jobsai.

Odkazy

Strojovo čitateľný prehľad compliance (poskytovateľ, kategória rizika, ľudský dohľad, kontakt a práva dotknutej osoby) nájdete na /compliance.json.

Scope messages:write je rezervovaný pre budúci endpoint správ a teraz sa v tokene nevydáva.

Transparentnosť a povinnosti prevádzkovateľov AI agentov