Punk Docs - Agent Activation

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 two distinct support-triage tickets through the Punk gateway, traces a read-only CRM tool, records feedback, and prints the route, run id, and dashboard run URL. After the second call it prints the observed route, whether the request remained live, and what evidence is still required before optimization.

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-sdk.ts
bun examples/anthropic-sdk.ts
bun examples/openai-tool-tracing.ts
bun examples/agent-activation.ts
bun examples/sdk-tool-loop.ts
bun examples/openrouter-sdk.ts
bun examples/langchain.ts

hosted-smoke-test.ts is the smallest hosted gateway check: two distinct support-triage tickets, receipt checks before each next request, dashboard run URLs, and second-run activation evidence.
openai-sdk.ts and anthropic-sdk.ts are the official client copies: two distinct tickets, receipt checks, and second-run activation evidence.
openai-tool-tracing.ts shows an existing official OpenAI client attaching local tool evidence to two distinct tickets, with receipt checks, exact model tool-request checks, and second-run activation evidence.
agent-activation.ts creates a Punk Agent, runs it twice with receipt checks before each next request, and prints workflow plus child gateway evidence.
sdk-tool-loop.ts requires one exact model tool request before each local lookup, then shows traceTool, tool-result caching, and second-run activation evidence for two distinct tickets.
openrouter-sdk.ts shows OpenRouter provider/model slugs through the OpenAI-compatible wire: two distinct tickets, receipt checks, and second-run activation evidence.
langchain.ts shows official ChatOpenAI through the same wire: two distinct tickets, onRun receipt checks, and second-run activation evidence.

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.

//DOCS Agent Activation