Dokumenty pre agent gateway

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.

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

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.

Prehľad nástrojov

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.

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.

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