Build your first agent

This page builds the same deterministic agent that ships as the minimal-tool-agent example: it reads one item from an immutable in-memory catalogue, produces a verified artifact, and exports an EvidenceRecord. No provider key, no network.

Compatibility: Pactmark 0.1.x. Every symbol below comes from @pactmark/agent, which re-exports the pieces of @pactmark/core you need for authoring.

1. Declare the schemas

Everything that crosses a boundary has a versioned schema identity. semanticRevision is what makes a meaning change visible even when the shape looks similar.

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(),
});

Use .strict(). An open object silently accepts fields the rest of the system has never reasoned about, and those fields end up in digests, contexts and evidence.

2. Define the tool

A tool is not just a function. It carries a security declaration that policy will enforce and that contributes to its registration digest.

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 and timeoutMs are not hints. They are enforced ceilings — a looping model cannot spend its way past them, which is exactly the point.

3. Describe the model boundary

Even a deterministic local model must declare a security profile and a resource profile. Those two digests travel with the run, so a change of provider, region, retention or output cap is visible rather than silent.

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

The driver itself is an async generator that yields either a tool_call or a final value. Here it is fully deterministic, which is what makes the example testable:

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

The driver references the tool by its registration digest, not by name. If the tool’s schema, security metadata or implementation version changes, that digest changes and the old reference stops resolving. Drift becomes an error instead of a surprise.

4. Compile the agent

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

Note default: "deny" — the type only accepts that value. There is no configuration in which a Pactmark policy defaults to allow.

5. Ask for the work

Figure 1. A WorkOrder is the request, not the agent. The same compiled agent can be accepted under many different work orders with different purposes, budgets and data classes.

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. Start it and read the results

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

Every read takes authority as its first argument. There is no ambient “current user” anywhere in the API, which is what makes cross-tenant access a compile-time conversation rather than a runtime accident.

What you just built

A compiled contract

Instructions, schemas, tools, model profiles, policy and verifiers, reduced to versioned identities with digests.

An append-only history

RunAccepted, ToolCallCompleted, RunCompleted — validated, ordered and replayable.

A content-addressed artifact

Output stored under the digest of its exact bytes, with verification bound to that digest.

An honest readiness report

production: false, because a memory store is not durability and the framework says so.

Next steps

Give the tool real teeth

Egress allowlists, effect strategies and what each ToolSecurity field actually enforces.

Add a human decision

Challenge, one-use proof, atomic consumption, and what approval can never waive.

Test the unhappy paths

Denial, cancellation, budget exhaustion, crash boundaries and registration drift.

Swap in a real provider

@pactmark/ai-sdk, credential references and why the adapter never sees a raw secret.

Getting started

Core concepts

Guides

Deployment

Production

Security

Build your first agent

1. Declare the schemas

2. Define the tool

3. Describe the model boundary

4. Compile the agent

5. Ask for the work

6. Start it and read the results

What you just built

A compiled contract

An append-only history

A content-addressed artifact

An honest readiness report

Next steps

Give the tool real teeth

Add a human decision

Test the unhappy paths

Swap in a real provider

​1. Declare the schemas

​2. Define the tool

​3. Describe the model boundary

​4. Compile the agent

​5. Ask for the work

​6. Start it and read the results

​What you just built

A compiled contract

An append-only history

A content-addressed artifact

An honest readiness report

​Next steps

Give the tool real teeth

Add a human decision

Test the unhappy paths

Swap in a real provider

1. Declare the schemas

2. Define the tool

3. Describe the model boundary

4. Compile the agent

5. Ask for the work

6. Start it and read the results

What you just built

Next steps