PUNKthe adaptive runtime

//DOCS Agent Activation

Starter app, flagship examples, and SDK activation checklist for new agent projects.

Agent Activation

Use this path when you want to go from package install to a visible Punk run quickly: model traffic, traced tools, feedback, route explanation, and savings.

Start From A Fresh App

npm create @punktechnologies/punk-agent@latest my-agent
cd my-agent
cp .env.example .env
# edit .env and set PUNK_API_KEY from https://app.punktechnologies.com
npm install
npm start

The generated app is plain Node.js ESM and depends only on @punktechnologies/sdk. It reads .env / .env.local, sends a support-triage request through the Punk gateway, traces a read-only CRM tool, records feedback, and prints route evidence.

Provider keys belong on the Punk gateway or in the tenant BYOK vault, not in the generated app.

Hosted Gateway

The starter uses Punk's hosted gateway and control plane:

PUNK_BASE_URL=https://app.punktechnologies.com
PUNK_API_KEY=pk_...

Create the API key in the Punk dashboard. Provider keys and BYOK credentials live in Punk, not in the generated app.

Existing App

If you already call a provider SDK, first route model traffic through Punk:

import OpenAI from "openai";
import { createPunkOpenAIConfig } from "@punktechnologies/sdk/openai";

const client = new OpenAI(createPunkOpenAIConfig({
  app: "support",
  agent: "triage-agent",
  subject: "user-123",
}));

Then add SDK runtime context where the gateway cannot infer it:

import { Punk } from "@punktechnologies/sdk";

const punk = new Punk({ app: "support", agent: "triage-agent", subject: "user-123" });

const lookupAccount = punk.traceTool({
  name: "crm.lookupAccount",
  sideEffectLevel: 1,
  ttlSeconds: 300,
  execute: async (args: { accountId: string }) => crm.get(args.accountId),
});

const result = await punk.chat({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Classify this refund ticket." }],
});

await punk.withRun(result, async () => lookupAccount({ accountId: "acct_42" }));
await punk.feedback(result.runId, 1);

Repo Examples

Run these with PUNK_API_KEY set:

bun examples/hosted-smoke-test.ts
bun examples/openai-tool-tracing.ts
bun examples/agent-activation.ts
bun examples/sdk-tool-loop.ts
bun examples/openrouter-sdk.ts
  • hosted-smoke-test.ts is the smallest hosted gateway check: one chat call twice, route/run ids, and explanation lookup.
  • openai-tool-tracing.ts shows an existing official OpenAI client attaching local tool evidence to the gateway run id.
  • agent-activation.ts creates a Punk Agent, runs it twice, and prints workflow plus child gateway evidence.
  • sdk-tool-loop.ts shows declared tool calls, traceTool, tool-result caching, and run evidence.
  • openrouter-sdk.ts shows OpenRouter provider/model slugs through the OpenAI-compatible wire.

What To Measure

Downloads are only a top-of-funnel signal. For SDK activation, watch:

  • successful starter runs;
  • route ids copied into support or bug reports;
  • examples opened from npm README links;
  • generated agents visible in the dashboard;
  • repeated runs producing cache, artifact, or other optimized routes;
  • feedback calls attached to completed run ids.