Agent-Gateway

Dokumentation des Agent-Gateways

Das Agent-Gateway ist eine separate Domain unter agents.jobsai.cz. Clients registrieren sich auf der Hauptwebsite und erhalten dann ein DPoP-gebundenes OAuth2-Token über Client-Credentials.

Wie das Agent-Gateway funktioniert

  1. Der Entwickler füllt die Registrierung aus und bestätigt die E-Mail-Adresse.
  2. Der Entwickler gibt bei der Registrierung einen öffentlichen DPoP-Schlüssel an (JWK oder JWKS-URL). Nach der E-Mail-Bestätigung zeigt das System client_id und client_secret einmalig an.
  3. Der Agent fordert ein Token unter agents.jobsai.cz/v1/oauth/token mit DPoP-Beweis an.
  4. Die MCP/A2A/ACP-Endpunkte prüfen die DPoP-Token-Bindung und die separate Kandidatenzustimmung, bei Unternehmens-Tools die Vollmacht des Unternehmens.

DPoP: Der htu-Claim muss der exakten Request-URL entsprechen. Die Nonce ist optional - lassen Sie sie weg oder verwenden Sie den letzten Wert aus dem DPoP-Nonce-Response-Header (eine selbst erzeugte Nonce wird abgelehnt). Der maßgebliche Token-Endpoint steht in den OAuth-Metadaten.

Idempotenz: Jede Schreiboperation (MCP submit_application, withdraw_application, propose_action und execute_approved_action, die Unternehmens-Tools create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job und confirm_job_open, ACP POST /runs und /runs/:id/cancel) erfordert einen Idempotency-Key-Header (UUID oder 8-255 Zeichen [a-zA-Z0-9_-]). Ohne ihn antwortet die API mit 400 idempotency_key_required. Streaming-Tools (subscribe, stream_matches) liefern über tools/call nur einen Verweis - den Stream selbst öffnen Sie mit einem zweiten Request mit Accept: text/event-stream.

Quickstart: MCP-Client verbinden

Von null zum ersten Aufruf in 3 Schritten. Der Server läuft auf agents.jobsai.cz (Streamable HTTP); Lese-Tools benötigen einen registrierten Agenten, Schreibzugriffe zusätzlich eine Einwilligungs-Envelope des Kandidaten und Unternehmens-Tools eine Vollmacht des Unternehmens.

1. Agent registrieren

Die Agenten-Registrierung stellt client_id und client_secret aus (einmalig angezeigt). Tokens kommen aus dem OAuth 2.1 Client-Credentials-Flow mit RFC 8414 Discovery (Links unten).

2. Server im Client hinzufügen

Claude Desktop und kompatible Clients: zur mcpServers-Konfiguration hinzufügen:

{
  "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. Ersten Aufruf machen

Nach der Verbindung lädt der Client tools/list. Beginnen Sie mit search_jobs (Suche in aktuellen Stellen) und get_job (Detail). Schreib-Tools erfordern eine Einwilligungs-Envelope - der Kandidat erteilt sie im Bereich Agentenzugriff seines Kontos. Unternehmens-Tools erfordern eine Vollmacht des Unternehmens - ein Inhaber oder Administrator stellt sie auf der Seite KI-Agenten im Unternehmenskonto aus.

Tool-Übersicht

ToolErforderlicher Zugriff
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

In tools/list trägt jedes Tool MCP-Annotationen: readOnlyHint bei Tools, die nur lesen, destructiveHint bei Tools, die etwas entfernen, zurückziehen, stornieren, ausblenden oder überschreiben können, und idempotentHint dort, wo ein wiederholter Aufruf nichts weiter ändert. Clients erkennen daran, wann sie den Nutzer fragen sollten; den Zugriff prüft weiterhin der Server.

Aktionen, die der Kandidat bestätigt

Die Tools propose_action, get_action_proposal und execute_approved_action bilden die Bestätigungsschleife. Der Agent schlägt eine Aktion nur vor; der Kandidat sieht den genauen Befehl in seinem JobsAI-Konto (Agentenzugriff, Bereich Freigaben), kann ihn bearbeiten und bestätigen, und erst danach führt der Agent genau diesen Befehl einmal aus. Die langfristige Zustimmungshülle ersetzt diese Bestätigung nicht. Der erforderliche Scope ist der Scope der vorgeschlagenen Aktion und muss sowohl im Token als auch in der Hülle vorhanden sein. Die Funktion ist nur dort verfügbar, wo der Betreiber sie aktiviert hat; andernfalls liefern die Tools approvals_unavailable.

Agent des Unternehmens

Die Tools list_employer_jobs, get_employer_job, list_employer_branches, create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job und confirm_job_open verwalten die Stellen eines Unternehmens. Der Agent ruft sie mit einer Vollmacht (Representation Envelope) auf, die ein Inhaber oder Administrator auf der Seite KI-Agenten im Unternehmenskonto ausstellt, und sendet sie bei jedem Aufruf im Header X-Jobsai-Representation-Envelope neben dem DPoP-Token. Der erforderliche Scope (employer_jobs:read, employer_jobs:write oder employer_jobs:publish) muss im Token und in der Vollmacht enthalten sein. Der Agent handelt als die Person, die die Vollmacht ausgestellt hat. Eine Vollmacht gilt 7, 30 oder 90 Tage und das Unternehmen kann sie jederzeit widerrufen.

  • Entwürfe (employer_jobs:read + employer_jobs:write): Stellen und Arbeitsorte des Unternehmens lesen, Entwürfe von Stellen und deren Bedingungen erstellen und bearbeiten. Veröffentlicht wird von einer Person aus dem Unternehmen.
  • Entwürfe und Veröffentlichen (zusätzlich employer_jobs:publish): veröffentlichen, veröffentlichte Stellen bearbeiten, archivieren und bestätigen, dass eine Stelle noch offen ist.

Veröffentlicht werden kann nur die Stelle eines verifizierten Unternehmens mit Gehaltsspanne. Texte durchlaufen die Antidiskriminierungsprüfung und der Agent kann keine Ausnahme geltend machen. Jeder Aufruf wird in das Aktivitätsprotokoll geschrieben, das das Unternehmen sieht. Ohne Vollmacht liefern die Tools representation_required, nach dem Widerruf representation_revoked. Änderungen nutzen eine optimistische Sperre: update_job braucht editHash und update_job_terms terms.revision aus get_employer_job; ein veralteter Wert liefert facts_changed (reason stale_edit_hash oder stale_terms_revision). Eine Änderung von Titel oder Beschreibung erhöht terms.revision und hebt die Bestätigung der Bedingungen auf, lesen Sie die Stelle deshalb vor der nächsten Änderung der Bedingungen erneut.

Hilfe für Unternehmen: KI-Agenten für Unternehmen

Beispiel-Prompts

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

Der Server ist auch im offiziellen MCP-Registry als cz.jobsai/jobsai gelistet.

Links

Eine maschinenlesbare Compliance-Übersicht (Anbieter, Risikokategorie, menschliche Aufsicht, Kontakt und Betroffenenrechte) ist unter /compliance.json verfügbar.

Der Scope messages:write ist für einen zukünftigen Messaging-Endpunkt reserviert und wird noch nicht in Tokens ausgestellt.

Transparenz und Pflichten für Betreiber von KI-Agenten