Dokumenty pro agent gateway

Jak funguje agent gateway

1. Vývojář vyplní registraci a potvrdí e-mail.
2. Vývojář při registraci uvede veřejný DPoP klíč (JWK nebo JWKS URL). Po potvrzení e-mailu systém jednorázově zobrazí client_id a client_secret.
3. Agent požádá o token na agents.jobsai.cz/v1/oauth/token s DPoP důkazem.
4. MCP/A2A/ACP endpointy ověří DPoP vazbu tokenu a samostatný souhlas kandidáta, u nástrojů pro firmy pověření firmy.

DPoP: claim htu musí odpovídat přesné URL požadavku. Nonce je volitelná - buď ji vynechte, nebo použijte poslední hodnotu z response hlavičky DPoP-Nonce (vlastní vygenerovaná nonce bude odmítnuta). Autoritativní token endpoint najdete v OAuth metadatech.

Idempotence: každá zapisovací operace (MCP submit_application, withdraw_application, propose_action a execute_approved_action, nástroje pro 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 nebo token 8-255 znaků [a-zA-Z0-9_-]). Bez ní vrací 400 idempotency_key_required. Streamovací nástroje (subscribe, stream_matches) vrací přes tools/call jen ukazatel - samotný stream otevřete druhým požadavkem s Accept: text/event-stream.

Quickstart: připojte MCP klienta

Od nuly k prvnímu volání ve 3 krocích. Server běží na agents.jobsai.cz (streamable HTTP), čtecí nástroje vyžadují registrovaného agenta, zápisy navíc souhlasovou obálku kandidáta a nástroje pro firmy pověření firmy.

1. Zaregistrujte agenta

Na stránce Registrace agenta získáte client_id a client_secret (zobrazí se jen jednou). Token vydává OAuth 2.1 client credentials flow, discovery dle RFC 8414 (odkazy níže).

2. Přidejte server do klienta

Claude Desktop a kompatibilní klienti: přidejte do konfigurace 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. Zavolejte první nástroj

Po připojení klient načte tools/list. Začněte s search_jobs (vyhledávání živých nabídek) a get_job (detail). Zápisové nástroje vyžadují souhlasovou obálku - kandidát ji udělí v sekci Agentní přístup ve svém účtu. Nástroje pro firmy vyžadují pověření firmy - vydá ho vlastník nebo správce na stránce AI agenti v účtu firmy.

Přehled nástrojů

Akce, které potvrzuje kandidát

Nástroje propose_action, get_action_proposal a execute_approved_action tvoří schvalovací smyčku. Agent akci pouze navrhne, kandidát vidí přesné znění příkazu ve svém účtu na JobsAI (sekce Agentní přístup, schválení), může ho upravit a potvrdit; teprve potom agent provede právě tento příkaz, a to jednou. Dlouhodobá souhlasová obálka potvrzení nenahrazuje. Požadovaný scope je scope navrhované akce a musí být v tokenu i v obálce. Funkce je dostupná jen v prostředích, kde ji provozovatel zapnul; jinde nástroje vracejí 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í nabídky jedné firmy. Agent je volá s pověřením (representation envelope), které vydá vlastník nebo správce firmy na stránce AI agenti v účtu firmy, a posílá ho při každém volání v hlavičce X-Jobsai-Representation-Envelope vedle DPoP tokenu. Potřebný scope (employer_jobs:read, employer_jobs:write nebo employer_jobs:publish) musí být v tokenu i v pověření. Agent jedná jako osoba, která pověření vydala. Pověření platí 7, 30 nebo 90 dní a firma ho může kdykoli odvolat.

• Koncepty (employer_jobs:read + employer_jobs:write): čtení nabídek a pracovišť firmy, zakládání a úprava konceptů nabídek a jejich podmínek. Zveřejňuje člověk z firmy.
• Koncepty i zveřejňování (navíc employer_jobs:publish): zveřejnění, úprava zveřejněných nabídek, archivace a potvrzení, že je pozice stále otevřená.

Zveřejnit lze jen nabídku ověřené firmy s mzdovým rozpětím. Texty procházejí antidiskriminační kontrolou a agent si nemůže uplatnit výjimku. Každé volání se zapisuje do logu činnosti, který firma vidí. Bez pověření vrací nástroje representation_required, po odvolání representation_revoked. Změny hlídá optimistický zámek: update_job chce editHash a update_job_terms terms.revision z get_employer_job; zastaralá hodnota vrací facts_changed (reason stale_edit_hash nebo stale_terms_revision). Změna názvu nebo popisu zvýší terms.revision a zruší potvrzení podmínek, proto nabídku před další úpravou podmínek načtěte znovu.

Nápověda pro firmy: AI agenti pro firmy

Ukázkové 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 najdete i v oficiálním MCP registry pod jménem cz.jobsai/jobsai.