İlk ajanınızı yazın

Bu sayfa, depoda minimal-tool-agent örneği olarak gelen deterministik ajanın aynısını kurar: değiştirilemez bir bellek-içi katalogdan tek bir kayıt okur, doğrulanmış bir artifact üretir ve bir EvidenceRecord dışa aktarır. Sağlayıcı anahtarı yok, ağ yok.

Uyumluluk: Pactmark 0.2.x. Aşağıdaki her sembol, yazım için ihtiyacınız olan @pactmark/core parçalarını yeniden dışa aktaran @pactmark/agent’tan gelir.

1. Şemaları beyan edin

Bir sınırı geçen her şeyin sürümlenmiş bir şema kimliği vardır. semanticRevision, biçim benzer görünse bile bir anlam değişikliğini görünür kılan şeydir.

src/example.ts

import { defineSchema } from "@pactmark/agent";
import { z } from "zod";

const input = defineSchema({
  id: "example.catalog.input",
  semanticRevision: "1",
  schema: z.object({ sku: z.string().min(1) }).strict(),
});

const toolInput = defineSchema({
  id: "example.catalog.lookup.input",
  semanticRevision: "1",
  schema: z.object({ sku: z.string().min(1) }).strict(),
});

const toolOutput = defineSchema({
  id: "example.catalog.lookup.output",
  semanticRevision: "1",
  schema: z
    .object({ sku: z.string(), name: z.string(), available: z.boolean() })
    .strict(),
});

const output = defineSchema({
  id: "example.catalog.output",
  semanticRevision: "1",
  schema: z
    .object({ summary: z.string(), source: z.literal("embedded-catalog") })
    .strict(),
});

.strict() kullanın. Açık bir nesne, sistemin geri kalanının hakkında hiç düşünmediği alanları sessizce kabul eder ve o alanlar özetlere, bağlamlara ve kanıta sızar.

2. Aracı tanımlayın

Bir araç yalnızca bir fonksiyon değildir. Politikanın zorlayacağı ve kayıt özetine katkı veren bir güvenlik beyanı taşır.

src/example.ts

import { defineTool } from "@pactmark/agent";

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 catalogue.",
  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 }),
  },
});

maxCallsPerRun ve timeoutMs birer öneri değildir. Zorlanan tavanlardır — döngüye giren bir model bunları harcayarak aşamaz; zaten amaç tam olarak budur.

3. Model sınırını tarif edin

Deterministik bir yerel model bile bir güvenlik profili ve bir kaynak profili beyan etmek zorundadır. Bu iki özet koşuyla birlikte taşınır; böylece sağlayıcı, bölge, saklama veya çıktı tavanı değişikliği sessiz değil görünür olur.

src/example.ts

import {
  defineModelResourceProfile,
  defineModelSecurityProfile,
} from "@pactmark/agent";

const security = defineModelSecurityProfile({
  id: "example.catalog.model@1",
  provider: "local",
  model: "deterministic",
  endpointOrigin: "https://local.invalid",
  credentialSlot: "local.none",
  allowedTenants: ["local"],
  allowedPurposes: ["service_delivery"],
  allowedDataClasses: ["public"],
  processingRegion: "process-local",
  retention: "none",
  logging: "none",
  training: "none",
  contractReference: "deterministic-fixture",
});

const resources = defineModelResourceProfile({
  id: "example.catalog.resources@1",
  implementationVersion: "1.0.0",
  maxInputBytesPerCall: 32_000,
  maxInputTokensPerCall: 4_000,
  maxOutputTokensPerCall: 500,
  maxStreamedOutputBytesPerCall: 32_000,
  maxStreamEventsPerCall: 100,
  maxToolResultToContextBytes: 8_000,
  maxContextSnapshotBytes: 64_000,
  maxRunModelInputBytes: 128_000,
  maxRunModelInputTokens: 16_000,
  maxRunModelOutputBytes: 64_000,
  maxRunModelOutputTokens: 2_000,
  maxRunToolResultToContextBytes: 32_000,
  estimator: "example.exact@1",
  providerOutputCap: "enforced",
});

Sürücünün kendisi, ya bir tool_call ya da bir final değeri üreten bir async generator’dır. Burada tamamen deterministiktir; örneği test edilebilir kılan da budur:

src/example.ts

import { digestCanonicalJson } from "@pactmark/core";
import type { CompiledModelDefinition } from "@pactmark/agent";

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 adıyla değil kayıt özetiyle atıfta bulunur. Aracın şeması, güvenlik meta verisi veya uygulama sürümü değişirse o özet değişir ve eski referans çözülmeyi bırakır. Sapma bir sürprize değil, bir hataya dönüşür.

4. Ajanı derleyin

src/example.ts

import { defineAgent, defineInstructions, definePolicy } from "@pactmark/agent";

export const catalogAgent = defineAgent({
  id: "minimal-catalog-agent",
  version: "0.1.0",
  description: "Reads one bounded deterministic catalogue fixture.",
  input,
  instructions: defineInstructions({
    text: "Read the catalogue fixture and report its bounded result.",
  }),
  model: model(),
  tools: { lookupCatalog },
  policy: definePolicy({
    id: "minimal-catalog.policy",
    implementationVersion: "1.0.0",
    default: "deny",
    rules: [{ riskClass: "R1", decision: "allow_with_grant" }],
  }),
  output,
  verifiers: ["schema@1"],
});

default: "deny" ifadesine dikkat edin — tip yalnızca bu değeri kabul eder. Bir Pactmark politikasının varsayılan olarak izin verdiği hiçbir yapılandırma yoktur.

5. İşi talep edin

Şekil 1. WorkOrder taleptir, ajan değildir. Aynı derlenmiş ajan, farklı amaçlar, bütçeler ve veri sınıflarıyla pek çok farklı iş emri altında kabul edilebilir.

src/example.ts

import {
  createCommandContext,
  createCommandId,
  createLocalAuthorityIssuer,
  createLocalRuntime,
  createWorkOrderRequest,
} from "@pactmark/agent";

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 request = createWorkOrderRequest({
  agent: { id: catalogAgent.id, version: catalogAgent.version },
  goal: "Check the bounded catalogue fixture.",
  input: { sku: "P-100" },
  context: {
    roleFamily: "operations",
    workflowId: "catalog-check",
    riskClass: "low",
  },
  workMode: "assist",
  autonomyMode: "assist",
  decisionOwner: { mode: "requesting_principal" },
  purpose: { code: "service_delivery", registryVersion: "general@1" },
  dataClass: "public",
  retention: { mode: "session" },
  requestedCapabilities: ["catalog:read"],
  budget: {
    maxTurns: 4,
    maxModelCalls: 4,
    maxToolCalls: 1,
    maxActiveExecutionMs: 10_000,
  },
});

6. Başlatın ve sonuçları okuyun

src/example.ts

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

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

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

const projection = await runtime.wait(authority, runId);
const artifacts = await runtime.getArtifacts(authority, runId);
const evidence = await runtime.getEvidence(authority, runId);
const readiness = runtime.evaluateReadiness({ profile: "production" });

Her okuma ilk argüman olarak authority alır. API’nin hiçbir yerinde ortamda dolaşan bir “geçerli kullanıcı” yoktur; tenant’lar arası erişimi bir çalışma-zamanı kazası değil, derleme-zamanı konuşması yapan şey budur.

Az önce ne inşa ettiniz

Derlenmiş bir sözleşme

Talimatlar, şemalar, araçlar, model profilleri, politika ve doğrulayıcılar — özetlerle sürümlenmiş kimliklere indirgenmiş hâlde.

Yalnızca-eklenen bir geçmiş

RunAccepted, ToolCallCompleted, RunCompleted — doğrulanmış, sıralı ve yeniden oynatılabilir.

İçerik-adresli bir artifact

Çıktı, tam baytlarının özeti altında saklanır ve doğrulama o özete bağlanır.

Dürüst bir hazırlık raporu

production: false, çünkü bellek deposu dayanıklılık değildir ve çerçeve bunu söyler.

Sonraki adımlar

Araca gerçek dişler takın

Egress izin listeleri, etki stratejileri ve her ToolSecurity alanının gerçekte ne zorladığı.

İnsan kararı ekleyin

Challenge, tek kullanımlık kanıt, atomik tüketim ve onayın asla feragat edemeyecekleri.

Mutsuz yolları test edin

Ret, iptal, bütçe tükenmesi, çökme sınırları ve kayıt sapması.

Gerçek bir sağlayıcı takın

@pactmark/ai-sdk, kimlik bilgisi referansları ve adaptörün neden ham sır görmediği.

Başlarken

Temel kavramlar

Rehberler

Dağıtım

Üretim

Güvenlik

İlk ajanınızı yazın

1. Şemaları beyan edin

2. Aracı tanımlayın

3. Model sınırını tarif edin

4. Ajanı derleyin

5. İşi talep edin

6. Başlatın ve sonuçları okuyun

Az önce ne inşa ettiniz

Derlenmiş bir sözleşme

Yalnızca-eklenen bir geçmiş

İçerik-adresli bir artifact

Dürüst bir hazırlık raporu

Sonraki adımlar

Araca gerçek dişler takın

İnsan kararı ekleyin

Mutsuz yolları test edin

Gerçek bir sağlayıcı takın

​1. Şemaları beyan edin

​2. Aracı tanımlayın

​3. Model sınırını tarif edin

​4. Ajanı derleyin

​5. İşi talep edin

​6. Başlatın ve sonuçları okuyun

​Az önce ne inşa ettiniz

Derlenmiş bir sözleşme

Yalnızca-eklenen bir geçmiş

İçerik-adresli bir artifact

Dürüst bir hazırlık raporu

​Sonraki adımlar

Araca gerçek dişler takın

İnsan kararı ekleyin

Mutsuz yolları test edin

Gerçek bir sağlayıcı takın

1. Şemaları beyan edin

2. Aracı tanımlayın

3. Model sınırını tarif edin

4. Ajanı derleyin

5. İşi talep edin

6. Başlatın ve sonuçları okuyun

Az önce ne inşa ettiniz

Sonraki adımlar