Agent API - Pactmark

Uyumluluk: Pactmark 0.2.x. Tam genel imzalar depodaki commit’lenmiş API Extractor raporlarından üretilir. Bu sayfa gerçekte kullanacağınız yüzeyi belgeler.

Yazım

`defineAgent(input)`

function defineAgent<I extends z.ZodType, O extends z.ZodType>(
  input: DefineAgentInput<I, O>,
): DefinedAgent<I, O>;

string

gerekli

Kararlı ajan tanımlayıcısı.

string

gerekli

Sözleşme sürümü.

string

gerekli

DefinedSchema<I>

gerekli

DefinedSchema<O>

gerekli

InstructionBundle

gerekli

CompiledModelDefinition

gerekli

DefinedPolicy

gerekli

readonly string[]

gerekli

Geçmesi gereken doğrulayıcı kimlikleri.

Record<string, DefinedTool>

İsteğe bağlı.

readonly string[]

Çalışma zamanının sağlaması gereken yetenekler; aksi hâlde koşu KAF_RUNTIME_CAPABILITY_MISSING ile başarısız olur.

Tip yardımcıları: InferAgentInput<A> ve InferAgentOutput<A>.

`defineTool(input)`

function defineTool<I extends z.ZodType, O extends z.ZodType>(
  input: DefineToolInput<I, O>,
): DefinedTool<I, O>;

string

gerekli

namespace.name@version ile eşleşir.

string

gerekli

string

gerekli

DefinedSchema

gerekli

Omit<ToolSecurity, 'schemaVersion'>

gerekli

{ kind: 'read'; execute(input, context) }

gerekli

toolRegistrationDigest dâhil registration: ToolRegistrationContract taşıyan bir DefinedTool döndürür.

`definePolicy(input)`

function definePolicy(input: DefinePolicyInput): DefinedPolicy;

"deny"

gerekli

"deny" literali. Başka hiçbir değer kabul edilmez.

{ riskClass, decision }[]

gerekli

decision; "deny", "allow_with_grant" veya "require_approval" olabilir.

`defineSchema` · `defineInstructions` · model profilleri

defineSchema({ id, semanticRevision, schema });
defineInstructions({ text, sourceName? });
defineModelSecurityProfile({ /* sağlayıcı, bölge, saklama, … */ });
defineModelResourceProfile({ /* çağrı ve koşu başına tavanlar */ });

Çalışma zamanı

`createLocalRuntime(input)`

function createLocalRuntime(input: {
  agents: readonly DefinedAgent[];
  authorityIssuer: AuthorityIssuer;
}): LocalRuntimeFacade;

Geliştirme ve testler için deterministik bellek destekli varsayılanlar. LocalRuntimeFacade, standart cepheye wait(authority, runId) ekler.

`createRuntime(input)`

function createRuntime(input: CreateRuntimeInput): RuntimeFacade;

RuntimeKernelConfig’i genişletir ve ek olarak contextStore, inputSubmissionStore ve egressBroker gerektirir; evidenceReader ve requiredRuntimeCapabilities isteğe bağlıdır. Her port açıktır — ortamda dolaşan varsayılan yoktur.

`RuntimeFacade`

Her metot ilk argüman olarak authority alır. Ortamda dolaşan bir geçerli kullanıcı yoktur.

Metot	Amaç
`start(authority, agent, request, command, options?)`	İşi kabul eder; `{ runId, workOrderId }` döner
`resume(authority, runId, command, options?)`	Devam ettirir; `{ runId, status }` döner
`cancel(authority, runId, reasonOrCommand, command?)`	İptal eder; projeksiyonu döner
`getRun(authority, runId)`	Güncel `RunProjection`
`events(authority, runId, { afterSequence?, signal? })`	Tekrarlı `AsyncIterable<RunEvent>`
`getArtifacts(authority, runId)`	`{ artifact, content }[]`
`getEvidence(authority, runId)`	`EvidenceRecord \| undefined`
`submitInput(authority, runId, requestId, value, command)`	Bir `InputRequested`’ı yanıtlar
`issueDecisionChallenge(authority, runId, decisionId, command)`	`{ challengeProof, expiresAt }`
`approve(authority, runId, decision, command)`	`{ approvalId, runId, automaticResume }`
`reject(authority, runId, decision, command)`	`{ decisionId, runId, automaticResume }`
`reconcileEffect(authority, runId, effectId, resolution, command)`	`{ status: "recovered" \| "abandoned" }`
`requestCompensation(authority, runId, effectId, request, command)`	`{ compensationRunId }`
`getCapabilities()`	`RuntimeCapabilities`
`evaluateReadiness({ profile })`	`RuntimeReadinessReport`

Yetki

`createLocalAuthorityIssuer(options?)`

const local = createLocalAuthorityIssuer({ issuerId?, now?, validityMs? });

const authority = local.issue({
  principal: { type: "user", id: "u-1" },
  tenant: { id: "acme" },
  authenticationStrength: "strong",
  decisionRoles: ["refund_approver"],
  requestCorrelationId: "req-…",
});

createLocalAuthorityIssuer; geliştirme, testler ve açıkça işaretlenmiş preview profilleri içindir. Üretimde yetki, kimliği doğrulanmış host eşlemenizden gelir — asla istek girdisiyle erişilebilen yerelde üretilmiş bir vericiden değil.

Komutlar

const command = createCommandContext({
  commandId: createCommandId(),
  operation: "run.start",
  payload: request,
});

Aynı kimlik ve aynı içerikle tekrarlanan bir komut aynı semantik sonucu döndürür. Farklı içerik KAF_HTTP_IDEMPOTENCY_CONFLICT, geçmiş bir ufuk KAF_COMMAND_IDEMPOTENCY_EXPIRED üretir.

Hazırlık

const report = evaluateRuntimeReadiness({
  capabilities: runtime.getCapabilities(),
  profile: "production",
  evaluatedAt: new Date().toISOString(),
  requiredCapabilities: ["durableStorage", "backgroundWakeup"],
  admissionConfigured: true,
  activeExecutionConfigured: true,
});

Profiller local, preview ve production’dır. Üretim hazırlığı; eksik dayanıklılığı, atomikliği, kayıtlı etki stratejilerini, sınırlı model kaynaklarını, kimlik bilgisi zorlamasını veya host yeteneğini reddeder.

Koşu olayları

Her olay tipi ve yükü.

Yapılandırma

createRuntime’ın beklediği portlar.

​Yazım

​defineAgent(input)

​defineTool(input)

​definePolicy(input)

​defineSchema · defineInstructions · model profilleri

​Çalışma zamanı

​createLocalRuntime(input)

​createRuntime(input)

​RuntimeFacade

​Yetki

​createLocalAuthorityIssuer(options?)

​Komutlar

​Hazırlık

Koşu olayları

Yapılandırma

Yazım

`defineAgent(input)`

`defineTool(input)`

`definePolicy(input)`

`defineSchema` · `defineInstructions` · model profilleri

Çalışma zamanı

`createLocalRuntime(input)`

`createRuntime(input)`

`RuntimeFacade`

Yetki

`createLocalAuthorityIssuer(options?)`

Komutlar

Hazırlık