HTTP API - Pactmark

Uyumluluk: Pactmark 0.2.x. OpenAPI belgesi çalışma zamanından türetilir — istek alanlarını ilgisiz dokümantasyona kopyalamak yerine onu imza kaynağı olarak kullanın.

İşleyiciyi bağlamak

import { createAgentFetchHandler, createOpenApiDocument } from "@pactmark/http";

const handler = createAgentFetchHandler({
  basePath: "/v1",
  runtime,
  authenticate: async (request) => resolvePrincipalAndTenant(request),
});

const openApi = createOpenApiDocument({ runtime, basePath: "/v1" });

Rotalar

Operasyonel

Metot	Yol	Amaç
`GET`	`/healthz`	Süreç canlı mı?
`GET`	`/readyz`	İstenen profili şu anda karşılayabiliyor mu?

Hazırlık kapalı biçimde başarısız olur. Üretim profili istenen bellek destekli bir çalışma zamanı hazır-değil döndürür.

Koşular

Metot	Yol	İşlem
`POST`	`/v1/runs`	`startRun`
`GET`	`/v1/runs/{runId}`	`getRun`
`POST`	`/v1/runs/{runId}/resume`	`resumeRun`
`POST`	`/v1/runs/{runId}/cancel`	`cancelRun`
`GET`	`/v1/runs/{runId}/events`	`streamEvents` (SSE)

İnsan etkileşimi

Metot	Yol	İşlem
`POST`	`/v1/runs/{runId}/inputs/{requestId}`	`submitInput`
`POST`	`/v1/runs/{runId}/decisions/{decisionId}/challenge`	`issueDecisionChallenge`
`POST`	`/v1/runs/{runId}/decisions/{decisionId}`	`submitDecision`

Etkiler

Metot	Yol	İşlem
`POST`	`/v1/runs/{runId}/effects/{effectId}/reconcile`	`reconcileEffect`
`POST`	`/v1/runs/{runId}/effects/{effectId}/compensate`	`requestCompensation`

Çıktı

Metot	Yol	İşlem
`GET`	`/v1/runs/{runId}/artifacts/{artifactId}`	`getArtifact`
`GET`	`/v1/runs/{runId}/artifacts/{artifactId}/verification`	`getVerification`
`GET`	`/v1/runs/{runId}/evidence`	`getEvidence`

Bir koşu başlatmak

POST /v1/runs
Content-Type: application/json
Authorization: Bearer …
Idempotency-Key: cmd_01J8…

{
  "agent": { "id": "support-refund-agent", "version": "2.1.0" },
  "goal": "ORD-88213 için iadeyi değerlendir.",
  "input": { "orderId": "ORD-88213" },
  "context": { "roleFamily": "customer_support", "workflowId": "refund-v2", "riskClass": "high" },
  "workMode": "augment",
  "autonomyMode": "delegate_review",
  "decisionOwner": { "mode": "registered_role", "role": "refund_approver" },
  "purpose": { "code": "customer_service", "registryVersion": "support@3" },
  "dataClass": "confidential",
  "retention": { "mode": "session" },
  "requestedCapabilities": ["orders:read", "payments:refund"],
  "budget": { "maxTurns": 8, "maxModelCalls": 8, "maxToolCalls": 6, "maxActiveExecutionMs": 60000 }
}

Tenant ve principal gövdede değildir. Enjekte edilmiş authenticator’dan gelirler.

Olayları akıtmak

Şekil 1. Sıra tekrarıyla SSE. afterSequence ile yeniden bağlanın; depo yenilerini takip etmeden önce kalıcı olaylardan yeniden oynatır.

GET /v1/runs/run_01J8…/events?afterSequence=42
Accept: text/event-stream

event: message
id: 43
data: {"eventType":"ToolCallRequested","sequence":43,"payload":{…}}

Idempotency

Idempotency anahtarınızı doğrulanmış CommandContext’e eşleyin. Aynı anahtar aynı içerikle aynı sonucu döndürür; aynı anahtar farklı içerikle KAF_HTTP_IDEMPOTENCY_CONFLICT, geçmiş bir ufuk KAF_COMMAND_IDEMPOTENCY_EXPIRED üretir.

Hatalar

{
  "type": "https://pactmark.dev/errors/authorization-binding-mismatch",
  "title": "KAF_AUTHORIZATION_BINDING_MISMATCH",
  "status": 403,
  "code": "KAF_AUTHORIZATION_BINDING_MISMATCH"
}

Kararlı bir kodla Problem Details. Tam kayıt ve yeniden denenebilirlik için bkz. Hata başvurusu.

Host’un yapılandırdıkları

Kimlik doğrulama

Principal, tenant, kimlik doğrulama gücü ve karar rollerini çözen enjekte edilmiş bir authenticator.

CORS ve kimlik bilgisi modu

İstemciniz için doğru olan ne ise — adaptör tahmin etmez.

CSRF

Çerezle kimlik doğrulanan tarayıcı istemcileri için gereklidir.

İstek, gövde ve süre sınırları

Bunları ayarlayın. Eksik bir gövde sınırı bir hizmet reddi yüzeyidir.

Admission

Tenant başına kotalar ve eşzamanlılık.

Açıklama seviyesi

Bir yanıtın ne kadarını açık ettiği ve loglara ne gittiği.

Bir istemci kopmasını taşımanın kaybı olarak ele alın — iptal değil ve işin durduğunun kanıtı da değil. Sonlanma durumunu kimliği doğrulanmış koşu API’sinden inceleyin ve kastettiğinizde açıkça iptal edin.

Akış ve istemciler

Yeniden bağlanma dâhil doğru bir istemci kurmak.

CLI

Aynı yüzeyler bir terminalden.

​İşleyiciyi bağlamak

​Rotalar

​Operasyonel

​Koşular

​İnsan etkileşimi

​Etkiler

​Çıktı

​Bir koşu başlatmak

​Olayları akıtmak

​Idempotency

​Hatalar

​Host’un yapılandırdıkları

Kimlik doğrulama

CORS ve kimlik bilgisi modu

CSRF

İstek, gövde ve süre sınırları

Admission

Açıklama seviyesi

Akış ve istemciler

CLI

İşleyiciyi bağlamak

Rotalar

Operasyonel

Koşular

İnsan etkileşimi

Etkiler

Çıktı

Bir koşu başlatmak

Olayları akıtmak

Idempotency

Hatalar

Host’un yapılandırdıkları