Minimal tool agent

Uyumluluk: Pactmark 0.2.x. Ağ yok, dış hesap yok. Bellek destekli çalışma zamanı geçici bir geliştirme profilidir ve kasıtlı olarak üretim hazırlığında başarısız olur.

Çalıştırın

pnpm --filter pactmark-example-minimal-tool test
pnpm --filter pactmark-example-minimal-tool dev

Beklenen çıktı:

{
  "runId": "run_01J…",
  "status": "completed",
  "eventTypes": ["RunAccepted", "ToolCallCompleted", "RunCompleted"],
  "evidenceDigest": "sha256:…",
  "productionReady": false
}

Neyi gösterir

Eksiksiz bir koşu

Kabul, planlama, tek araç çağrısı, tamamlanma — sonunda gerçek bir artifact ve kanıt kaydıyla.

Deterministik bir model sürücüsü

Önce tool_call, sonra final üreten bir async generator. Tamamen yeniden üretilebilir.

Mümkün olan en küçük varsayılan-ret politika

R1 için tek kural; geri kalan her şey reddedilir.

Dürüst hazırlık

productionReady: false, çünkü bellek deposu dayanıklılık değildir.

Araç

examples/minimal-tool-agent/src/example.ts

const fixture = Object.freeze({
  sku: "P-100",
  name: "Portable notebook",
  available: true,
});

export const lookupCatalog = defineTool({
  id: "catalog.lookup@1",
  implementationVersion: "1.0.0",
  description: "Read one item from the immutable example catalog.",
  input: toolInput,
  output: toolOutput,
  security: {
    riskClass: "R1",
    dataClasses: ["public"],
    reversibility: "not_applicable",
    requiredScopes: ["catalog:read"],
    egress: { mode: "none" },
    networkEnforcement: "declared_ok",
    maxCallsPerRun: 1,
    timeoutMs: 1_000,
  },
  operation: {
    kind: "read",
    execute: ({ sku }) =>
      Promise.resolve({ ...fixture, available: fixture.sku === sku }),
  },
});

egress: { mode: "none" } ve dondurulmuş bir fixture birlikte, bu aracın hiçbir şeye ulaşamayacağı anlamına gelir. İyi bir ilk örnek olmasının nedeni budur — hakkındaki hiçbir şey sizi şaşırtamaz.

Model sürücüsü

function model(): CompiledModelDefinition {
  let turn = 0;
  return {
    modelSecurityProfileDigest: security.modelSecurityProfileDigest,
    modelResourceProfileDigest: resources.modelResourceProfileDigest,
    modelAdapterRegistrationDigest: digestCanonicalJson({
      adapter: "example.catalog@1",
    }),
    modelConfig: { kind: "deterministic" },
    credentialMode: "ambient_preview",
    driver: {
      capabilities,
      async *invoke() {
        turn += 1;
        yield turn === 1
          ? {
              type: "tool_call",
              value: {
                toolRegistrationDigest:
                  lookupCatalog.registration.toolRegistrationDigest,
                input: { sku: "P-100" },
                targetDigest: digestCanonicalJson({
                  source: "embedded-catalog",
                  sku: "P-100",
                }),
              },
            }
          : {
              type: "final",
              value: {
                summary: "Portable notebook is available.",
                source: "embedded-catalog",
              },
            };
      },
    },
  };
}

Sürücü araca kayıt özetiyle ad verir. Bu tesadüf değil — örneğin, şeması veya güvenlik meta verisi değişmiş bir araca eski bir referansla ulaşılamayacağını gösterme biçimidir.

Yetenek beyanı

const capabilities: RuntimeCapabilities = {
  schemaVersion: "1",
  executionProfile: "ephemeral",
  durableStorage: false,
  protectedContext: false,
  protectedWorkOrders: false,
  protectedInputSubmissions: false,
  streaming: true,
  cancellation: true,
  sandbox: "unsafe_local",
  networkPolicy: "declared",
  backgroundWakeup: false,
  atomicCommandAndWakeup: false,
  humanDecisions: false,
  typedInput: false,
  effectReconciliation: false,
  compensation: false,
  modelCredentials: false,
  toolCredentials: false,
  telemetry: "none",
  transactionDomains: [],
};

Bunu, bu çalışma zamanının yapamadıklarının listesi olarak okuyun. Her biri hakkında dürüsttür; bu yüzden üretim profili hazırlığı bozularak değil başarısız olarak sonuçlanır.

Koşu

const local = createLocalAuthorityIssuer();
const authority = local.issue({
  principal: { type: "user", id: "example-user" },
  tenant: { id: "local" },
});
const runtime = createLocalRuntime({
  agents: [catalogAgent],
  authorityIssuer: local.issuer,
});

const { runId } = await runtime.start(authority, catalogAgent, request, command);

const events = [];
for await (const event of runtime.events(authority, runId)) events.push(event);

return {
  runId,
  projection: await runtime.wait(authority, runId),
  events,
  artifacts: await runtime.getArtifacts(authority, runId),
  evidence: await runtime.getEvidence(authority, runId),
  productionReadiness: runtime.evaluateReadiness({ profile: "production" }),
};

Ne çıkıyor

Şekil 1. Bu minimal koşu bile yapının tamamını üretir: sıralı olaylar, türetilmiş bir projeksiyon, içerik-adresli bir artifact ve sınırlı bir kanıt kaydı.

Neyi desteklemez

Sonuç yalnızca bu koşu sırasında gömülü fixture’ın içerdiğini destekler. Bellek destekli çalışma zamanı geçici bir geliştirme profilidir ve kasıtlı olarak üretim hazırlığında başarısız olur. Ağ veya dış hesap kullanılmadığı için buradaki hiçbir şey gerçek bir katalog servisi hakkında kanıt değildir.

Bir şey öğrenmek için değiştirin

maxToolCalls değerini 0 yapın

Koşunun tamamlanmayla değil bütçeyle sonlandığını izleyin.

Politikadan R1 kuralını kaldırın

Araç çağrısı KAF_POLICY_DENIED ile reddedilir — ve araç yürütücüsü sıfır çağrı kaydeder.

Sürümü artırmadan aracın girdi şemasını değiştirin

Kayıt özeti değişir ve sürücünün referansı artık çözülmez.

Fixture'da olmayan bir sku isteyin

available: false — araç hata değil dürüst bir olumsuz döndürür.

Kendiniz yazın

Aynı ajan, sıfırdan yazılmış ve her nesnesi açıklanmış hâli.

Workspace agent

Bir üst basamak: gerçek ret yollarıyla sınırlı dosya sistemi erişimi.

​Çalıştırın

​Neyi gösterir

Eksiksiz bir koşu

Deterministik bir model sürücüsü

Mümkün olan en küçük varsayılan-ret politika

Dürüst hazırlık

​Araç

​Model sürücüsü

​Yetenek beyanı

​Koşu

​Ne çıkıyor

​Neyi desteklemez

​Bir şey öğrenmek için değiştirin

Kendiniz yazın

Workspace agent

Çalıştırın

Neyi gösterir

Araç

Model sürücüsü

Yetenek beyanı

Koşu

Ne çıkıyor

Neyi desteklemez

Bir şey öğrenmek için değiştirin