@andreprado/agentkit 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -77
- package/docs/guides/add-channel.md +14 -92
- package/docs/guides/add-knowledge.md +0 -21
- package/docs/guides/add-tool.md +5 -11
- package/docs/guides/channel-security.md +3 -207
- package/docs/guides/connect-discord.md +7 -172
- package/docs/guides/connect-slack.md +6 -121
- package/docs/guides/connect-telegram.md +6 -165
- package/docs/guides/connect-whatsapp-evolution.md +6 -116
- package/docs/guides/connect-whatsapp-uazapi.md +6 -134
- package/docs/guides/connect-whatsapp-zapster.md +6 -202
- package/docs/guides/create-agent.md +5 -14
- package/docs/guides/debug-channel.md +4 -156
- package/docs/guides/improve-local.md +13 -0
- package/docs/guides/local-only-migration.md +35 -0
- package/docs/guides/replay-local-traces.md +11 -0
- package/docs/guides/run-evals.md +2 -4
- package/docs/guides/security-rules.md +5 -154
- package/docs/guides/use-jev.md +3 -6
- package/docs/guides/use-provider.md +0 -3
- package/docs/guides/write-feedback.md +10 -0
- package/docs/llms-full.txt +27 -448
- package/docs/llms.txt +8 -44
- package/package.json +2 -4
- package/src/cli/commands/channels.ts +8 -1613
- package/src/cli/commands/feedback.ts +8 -86
- package/src/cli/constants.ts +0 -3
- package/src/cli/flags.ts +0 -28
- package/src/cli/help.ts +16 -92
- package/src/cli/index.ts +15 -1091
- package/src/index.ts +6 -158
- package/src/providers/pi.ts +2 -0
- package/src/runtime/channels/discord.ts +16 -8
- package/src/runtime/channels/generic-webhook.ts +21 -313
- package/src/runtime/channels/net-guard.ts +480 -0
- package/src/runtime/channels/provider-fetch.ts +54 -0
- package/src/runtime/channels/slack.ts +9 -3
- package/src/runtime/channels/telegram.ts +43 -10
- package/src/runtime/channels/whatsapp-evolution.ts +33 -60
- package/src/runtime/channels/whatsapp-uazapi.ts +33 -164
- package/src/runtime/channels/whatsapp-zapster.ts +35 -7
- package/src/runtime/chat.ts +5 -3
- package/src/runtime/config.ts +36 -147
- package/src/runtime/database.ts +2 -2
- package/src/runtime/dev-server.ts +8 -8
- package/src/runtime/env.ts +11 -0
- package/src/runtime/improve.ts +2 -262
- package/src/runtime/inspect.ts +13 -73
- package/src/runtime/knowledge/embeddings.ts +45 -7
- package/src/runtime/knowledge/ingest.ts +70 -7
- package/src/runtime/knowledge/tool.ts +16 -2
- package/src/runtime/knowledge/vector.ts +31 -31
- package/src/runtime/tool-runner.ts +5 -3
- package/src/runtime/tools.ts +10 -14
- package/src/storage/sqlite.ts +11 -32
- package/src/templates/blank.ts +15 -102
- package/src/templates/common.ts +60 -0
- package/src/templates/dentista.ts +7 -74
- package/src/templates/skills/agentkit-capsule/SKILL.md +5 -7
- package/src/templates/skills/agentkit-capsule/references/docs-router.md +2 -3
- package/src/templates/skills/agentkit-channels/SKILL.md +6 -119
- package/src/templates/skills/agentkit-channels/references/channel-buffering.md +0 -9
- package/src/templates/skills/agentkit-channels/references/channel-debugging.md +1 -64
- package/src/templates/skills/agentkit-channels/references/discord.md +2 -92
- package/src/templates/skills/agentkit-channels/references/slack.md +2 -55
- package/src/templates/skills/agentkit-channels/references/telegram.md +2 -71
- package/src/templates/skills/agentkit-channels/references/whatsapp-evolution.md +2 -56
- package/src/templates/skills/agentkit-channels/references/whatsapp-uazapi.md +2 -53
- package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md +2 -70
- package/src/templates/skills/agentkit-database/SKILL.md +2 -4
- package/src/templates/skills/agentkit-evals/SKILL.md +1 -1
- package/src/templates/skills/agentkit-improve/SKILL.md +6 -85
- package/src/templates/skills/agentkit-improve/references/trace-packets.md +1 -1
- package/src/templates/skills/agentkit-provider/SKILL.md +0 -1
- package/src/templates/skills/agentkit-security/SKILL.md +1 -3
- package/src/templates/skills/agentkit-tools/SKILL.md +1 -1
- package/src/templates/skills/agentkit-tools/examples/database-write.tool.md +1 -2
- package/src/templates/skills/agentkit-troubleshooting/SKILL.md +5 -11
- package/src/templates/support.ts +8 -92
- package/docs/guides/add-managed-composio.md +0 -165
- package/docs/guides/improve-from-production.md +0 -151
- package/docs/guides/prepare-deploy.md +0 -227
- package/docs/guides/replay-production-traces.md +0 -72
- package/docs/guides/send-feedback.md +0 -135
- package/src/cli/cloud-client.ts +0 -377
- package/src/cli/deploy-chat-ui.ts +0 -606
- package/src/cli/deploy-readiness.ts +0 -561
- package/src/cloud/artifact.ts +0 -139
- package/src/cloud/client.ts +0 -80
- package/src/cloud/contracts.ts +0 -63
- package/src/cloud/index.ts +0 -3
- package/src/runtime/build.ts +0 -43
- package/src/runtime/core/deploy-state.ts +0 -54
- package/src/runtime/core/manifest.ts +0 -283
- package/src/runtime/core/targets.ts +0 -133
- package/src/runtime/deploy-readiness.ts +0 -135
- package/src/runtime/deploy.ts +0 -1
- package/src/runtime/integrations/composio.ts +0 -425
- package/src/runtime/targets/cloudflare/build.ts +0 -3319
- package/src/runtime/targets/container/build.ts +0 -146
- package/src/runtime/targets/container/server.ts +0 -33
- package/src/runtime/targets/vps/deploy.ts +0 -223
- package/src/templates/skills/agentkit-deploy/SKILL.md +0 -52
- package/src/templates/skills/agentkit-integrations/SKILL.md +0 -98
package/src/storage/sqlite.ts
CHANGED
|
@@ -378,6 +378,7 @@ export class SqliteAgentKitStore {
|
|
|
378
378
|
usage?: ProviderRunResult["usage"];
|
|
379
379
|
errorCode?: string;
|
|
380
380
|
errorMessage?: string;
|
|
381
|
+
secretValues?: string[];
|
|
381
382
|
}): void {
|
|
382
383
|
this.sqlite(() => {
|
|
383
384
|
this.db
|
|
@@ -403,7 +404,7 @@ export class SqliteAgentKitStore {
|
|
|
403
404
|
$outputTokens: input.usage?.outputTokens ?? null,
|
|
404
405
|
$totalTokens: input.usage?.totalTokens ?? null,
|
|
405
406
|
$errorCode: input.errorCode ?? null,
|
|
406
|
-
$errorMessage: redactSecrets(input.errorMessage ?? null),
|
|
407
|
+
$errorMessage: redactSecrets(input.errorMessage ?? null, input.secretValues),
|
|
407
408
|
});
|
|
408
409
|
});
|
|
409
410
|
}
|
|
@@ -672,11 +673,8 @@ export class SqliteAgentKitStore {
|
|
|
672
673
|
continue;
|
|
673
674
|
}
|
|
674
675
|
|
|
675
|
-
const statements = splitSqlStatements(migration.sql);
|
|
676
676
|
this.transaction(() => {
|
|
677
|
-
|
|
678
|
-
this.db.exec(statement);
|
|
679
|
-
}
|
|
677
|
+
this.db.exec(migration.sql);
|
|
680
678
|
|
|
681
679
|
this.db
|
|
682
680
|
.prepare("INSERT INTO agentkit_app_migrations (id, applied_at) VALUES ($id, $appliedAt)")
|
|
@@ -690,28 +688,16 @@ export class SqliteAgentKitStore {
|
|
|
690
688
|
}
|
|
691
689
|
|
|
692
690
|
applyApplicationSchema(source: string): void {
|
|
693
|
-
this.sqlite(() => {
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
if (statements.length === 0) {
|
|
697
|
-
return;
|
|
698
|
-
}
|
|
699
|
-
|
|
700
|
-
const transaction = () => this.transaction(() => {
|
|
701
|
-
for (const statement of statements) {
|
|
702
|
-
this.db.exec(statement);
|
|
703
|
-
}
|
|
704
|
-
});
|
|
705
|
-
|
|
706
|
-
transaction();
|
|
707
|
-
});
|
|
691
|
+
this.sqlite(() => this.transaction(() => {
|
|
692
|
+
this.db.exec(source);
|
|
693
|
+
}));
|
|
708
694
|
}
|
|
709
695
|
|
|
710
696
|
executeApplicationSql(sql: string, args: DatabaseArgs = []): DatabaseResult {
|
|
711
697
|
return this.sqlite(() => {
|
|
712
698
|
const statement = this.db.prepare(sql);
|
|
713
699
|
const columns = sqliteColumnNames(statement);
|
|
714
|
-
const bindings =
|
|
700
|
+
const bindings = args.map((value) => typeof value === "boolean" ? Number(value) : value);
|
|
715
701
|
|
|
716
702
|
if (columns.length > 0) {
|
|
717
703
|
return {
|
|
@@ -998,21 +984,14 @@ function normalizeLastInsertRowid(value: number | bigint): number | string {
|
|
|
998
984
|
return Number.isSafeInteger(numberValue) ? numberValue : value.toString();
|
|
999
985
|
}
|
|
1000
986
|
|
|
1001
|
-
function splitSqlStatements(source: string): string[] {
|
|
1002
|
-
return source
|
|
1003
|
-
.split(";")
|
|
1004
|
-
.map((statement) => statement.trim())
|
|
1005
|
-
.filter(Boolean);
|
|
1006
|
-
}
|
|
1007
|
-
|
|
1008
987
|
function serializeJson(value: unknown, secretValues: string[] = []): string {
|
|
1009
988
|
return redactSecrets(JSON.stringify(value), secretValues);
|
|
1010
989
|
}
|
|
1011
990
|
|
|
1012
|
-
function redactSecrets(value: string, secretValues?: string[]): string;
|
|
1013
|
-
function redactSecrets(value: null, secretValues?: string[]): null;
|
|
1014
|
-
function redactSecrets(value: string | null, secretValues?: string[]): string | null;
|
|
1015
|
-
function redactSecrets(value: string | null, secretValues: string[] = []): string | null {
|
|
991
|
+
export function redactSecrets(value: string, secretValues?: string[]): string;
|
|
992
|
+
export function redactSecrets(value: null, secretValues?: string[]): null;
|
|
993
|
+
export function redactSecrets(value: string | null, secretValues?: string[]): string | null;
|
|
994
|
+
export function redactSecrets(value: string | null, secretValues: string[] = []): string | null {
|
|
1016
995
|
if (value === null) {
|
|
1017
996
|
return null;
|
|
1018
997
|
}
|
package/src/templates/blank.ts
CHANGED
|
@@ -1,65 +1,11 @@
|
|
|
1
1
|
import type { AgentTemplate } from ".";
|
|
2
|
+
import { commonTemplateFiles } from "./common";
|
|
2
3
|
|
|
3
4
|
export const blankTemplate: AgentTemplate = {
|
|
4
5
|
name: "blank",
|
|
5
6
|
files(projectName: string, context = {}) {
|
|
6
|
-
const storageName = projectName.toLowerCase().replace(/_/g, "-");
|
|
7
|
-
|
|
8
7
|
return [
|
|
9
|
-
|
|
10
|
-
path: "package.json",
|
|
11
|
-
contents: `${JSON.stringify(
|
|
12
|
-
{
|
|
13
|
-
name: projectName,
|
|
14
|
-
private: true,
|
|
15
|
-
type: "module",
|
|
16
|
-
scripts: {
|
|
17
|
-
agentkit: "agentkit",
|
|
18
|
-
dev: "agentkit dev",
|
|
19
|
-
chat: "agentkit chat",
|
|
20
|
-
eval: "agentkit eval run",
|
|
21
|
-
typecheck: "tsc --noEmit",
|
|
22
|
-
},
|
|
23
|
-
dependencies: {
|
|
24
|
-
"@andreprado/agentkit": context.agentkitDependency ?? "workspace:*",
|
|
25
|
-
},
|
|
26
|
-
devDependencies: {
|
|
27
|
-
"@types/node": "^24.12.4",
|
|
28
|
-
typescript: "^5.9.3",
|
|
29
|
-
},
|
|
30
|
-
},
|
|
31
|
-
null,
|
|
32
|
-
2,
|
|
33
|
-
)}
|
|
34
|
-
`,
|
|
35
|
-
},
|
|
36
|
-
{
|
|
37
|
-
path: "tsconfig.json",
|
|
38
|
-
contents: `${JSON.stringify(
|
|
39
|
-
{
|
|
40
|
-
compilerOptions: {
|
|
41
|
-
target: "ES2022",
|
|
42
|
-
module: "ESNext",
|
|
43
|
-
moduleResolution: "Bundler",
|
|
44
|
-
strict: true,
|
|
45
|
-
skipLibCheck: true,
|
|
46
|
-
noEmit: true,
|
|
47
|
-
types: ["node"],
|
|
48
|
-
},
|
|
49
|
-
include: ["**/*.ts"],
|
|
50
|
-
},
|
|
51
|
-
null,
|
|
52
|
-
2,
|
|
53
|
-
)}
|
|
54
|
-
`,
|
|
55
|
-
},
|
|
56
|
-
{
|
|
57
|
-
path: ".gitignore",
|
|
58
|
-
contents: `.env
|
|
59
|
-
.agentkit/
|
|
60
|
-
node_modules/
|
|
61
|
-
`,
|
|
62
|
-
},
|
|
8
|
+
...commonTemplateFiles(projectName, context),
|
|
63
9
|
{
|
|
64
10
|
path: ".env.schema",
|
|
65
11
|
contents: `# Optional: only needed after switching agentkit.config.ts to a Pi-backed real provider.
|
|
@@ -75,7 +21,7 @@ OPENCODE_API_KEY=
|
|
|
75
21
|
|
|
76
22
|
export default defineAgent({
|
|
77
23
|
name: "${projectName}",
|
|
78
|
-
runtime: "
|
|
24
|
+
runtime: "local",
|
|
79
25
|
provider: {
|
|
80
26
|
name: "test",
|
|
81
27
|
model: "fake",
|
|
@@ -90,12 +36,11 @@ export default defineAgent({
|
|
|
90
36
|
driver: "agentkit",
|
|
91
37
|
path: ".agentkit/agentkit.db",
|
|
92
38
|
database: {
|
|
93
|
-
driver: "
|
|
39
|
+
driver: "sqlite",
|
|
94
40
|
schema: "./schema.sql",
|
|
95
41
|
},
|
|
96
42
|
files: {
|
|
97
|
-
driver: "
|
|
98
|
-
bucket: "agentkit-${storageName}-files",
|
|
43
|
+
driver: "local",
|
|
99
44
|
prefix: "${projectName}",
|
|
100
45
|
},
|
|
101
46
|
},
|
|
@@ -145,7 +90,7 @@ export default defineEval({
|
|
|
145
90
|
|
|
146
91
|
This is an AgentKit Agent Capsule.
|
|
147
92
|
|
|
148
|
-
The capsule root is the runtime boundary. Run, inspect,
|
|
93
|
+
The capsule root is the runtime boundary. Run, inspect, and evaluate from this directory.
|
|
149
94
|
|
|
150
95
|
## Coding Agent Workflow
|
|
151
96
|
|
|
@@ -175,7 +120,7 @@ Do not only edit prompts. For every meaningful requirement in the owner's reques
|
|
|
175
120
|
- schema/migration plus tool for durable records;
|
|
176
121
|
- eval for privacy, confirmation, required fields, date/time behavior, business rules, and regressions;
|
|
177
122
|
- fixture, seed data, fake branch, or direct tool check for integrations and failure paths;
|
|
178
|
-
-
|
|
123
|
+
- local config and secret checks for channels and external tools.
|
|
179
124
|
|
|
180
125
|
If a rule protects privacy, money, bookings, external writes, customer data, business hours, or safety, it must have an eval or deterministic check before you call the capsule done. If a real conversation exposes a bug, convert it into the smallest regression eval before or alongside the fix.
|
|
181
126
|
|
|
@@ -202,15 +147,15 @@ If a rule protects privacy, money, bookings, external writes, customer data, bus
|
|
|
202
147
|
## Testing With A UI
|
|
203
148
|
|
|
204
149
|
- Local UI: run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
|
|
205
|
-
- Hosted UI: after \`npm run agentkit -- deploy\`, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
|
|
206
150
|
- \`test/fake\` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality.
|
|
207
151
|
- Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.
|
|
208
152
|
|
|
209
|
-
This blank capsule starts with the built-in \`test/fake\` provider, so local chat works without secrets or internet access. It is also deploy-ready by default: the user can edit the prompt, add tools, and run \`npm run agentkit -- deploy\`.
|
|
210
153
|
|
|
211
154
|
## Local Runtime Contract
|
|
212
155
|
|
|
213
|
-
|
|
156
|
+
The default test/fake provider works without secrets.
|
|
157
|
+
|
|
158
|
+
\`agentkit dev\`, \`agentkit chat\`, and \`agentkit tool\` use AgentKit-managed local development storage. If the capsule has \`schema.sql\`, AgentKit applies it before tools run.
|
|
214
159
|
|
|
215
160
|
- Chat: \`http://localhost:4123\`
|
|
216
161
|
- API: \`http://localhost:4123/v1/chat\`
|
|
@@ -236,26 +181,15 @@ export const myTool = defineTool({
|
|
|
236
181
|
});
|
|
237
182
|
\`\`\`
|
|
238
183
|
|
|
239
|
-
Use \`ctx.db\` as the canonical helper. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Use \`ctx.db.batch([...])\` for atomic writes; local tools can also use \`ctx.db.transaction(async (tx) => ...)\`. Do not import local database drivers or Node-only APIs in tools. AgentKit owns local
|
|
184
|
+
Use \`ctx.db\` as the canonical helper. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Use \`ctx.db.batch([...])\` for atomic writes; local tools can also use \`ctx.db.transaction(async (tx) => ...)\`. Do not import local database drivers or Node-only APIs in tools. AgentKit owns local database storage.
|
|
240
185
|
|
|
241
186
|
\`schema.sql\` is an idempotent bootstrap file. Use \`CREATE TABLE IF NOT EXISTS\`, \`CREATE INDEX IF NOT EXISTS\`, and safe additive changes. Use ordered \`migrations/*.sql\` for production-shaped schema evolution; \`npm run agentkit -- db migrate\` applies unapplied local migrations before \`schema.sql\`.
|
|
242
187
|
|
|
243
|
-
## Hosted Deploy
|
|
244
|
-
|
|
245
|
-
- \`npm run agentkit -- deploy\`: deploy the capsule.
|
|
246
|
-
- AgentKit owns the hosted runtime, managed database, file storage, and production secret injection.
|
|
247
|
-
- Local scaffold, dev, chat, eval, inspect, database, and build commands are token-free.
|
|
248
|
-
- Hosted deploy requires an invited AgentKit Cloud alpha token. If no token is stored yet, ask the owner for one and run \`npm run agentkit -- login --token <token>\`.
|
|
249
|
-
- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`, not into committed files or shell history.
|
|
250
|
-
- The user should not choose a deploy target, create hosted databases, create buckets, copy production secrets into this capsule, or run operator/admin commands.
|
|
251
|
-
- Hosted deploy writes the local chat/UI deploy access token to \`.agentkit/chat-access-token.json\`. Create extra client-facing tokens with \`npm run agentkit -- access token create <name> --out <path>\`.
|
|
252
|
-
- Use \`npm run agentkit -- deploy --smoke "hello"\` or \`npm run agentkit -- deploy smoke --message "hello"\` for an official hosted chat smoke check.
|
|
253
|
-
|
|
254
188
|
## Rules
|
|
255
189
|
|
|
256
190
|
- Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
|
|
257
191
|
- Real providers are resolved by AgentKit through the internal Pi SDK backend; keep project code on \`@andreprado/agentkit\`.
|
|
258
|
-
- The owner must choose the real provider before you switch from \`test/fake\`. Update \`agentkit.config.ts\`, \`.env.schema\`, and local
|
|
192
|
+
- The owner must choose the real provider before you switch from \`test/fake\`. Update \`agentkit.config.ts\`, \`.env.schema\`, and local secrets after that choice.
|
|
259
193
|
- Do not commit \`.env\` or \`.agentkit/\`.
|
|
260
194
|
- Edit the agent contract in \`agentkit.config.ts\`.
|
|
261
195
|
- Edit instructions in \`prompts/instructions.md\`.
|
|
@@ -324,16 +258,9 @@ npm run dev
|
|
|
324
258
|
|
|
325
259
|
Open the printed \`Chat:\` URL and tell the owner the exact URL.
|
|
326
260
|
|
|
327
|
-
Hosted deploy UI:
|
|
328
261
|
|
|
329
|
-
\`\`\`sh
|
|
330
|
-
npm run agentkit -- deploy
|
|
331
|
-
npm run agentkit -- chat-ui --deploy
|
|
332
|
-
\`\`\`
|
|
333
262
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them. After they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
|
|
263
|
+
Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them. After they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, then rerun chat/UI checks.
|
|
337
264
|
|
|
338
265
|
If you add a tool, also run a fake-provider tool smoke test:
|
|
339
266
|
|
|
@@ -349,20 +276,6 @@ npm run agentkit -- docs llms
|
|
|
349
276
|
|
|
350
277
|
Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
|
|
351
278
|
|
|
352
|
-
## Hosted Deploy
|
|
353
|
-
|
|
354
|
-
This capsule is hosted-deploy ready by default.
|
|
355
|
-
|
|
356
|
-
1. Keep \`runtime: "edge"\` and \`storage.driver: "agentkit"\`.
|
|
357
|
-
2. Put agent-owned tables in \`schema.sql\`. AgentKit applies it locally and migrates/provisions hosted storage during deploy.
|
|
358
|
-
3. Run \`npm run agentkit -- build\` only when you want to validate the artifact locally.
|
|
359
|
-
4. If the owner has not logged in yet, ask for an invited AgentKit Cloud alpha token and run \`npm run agentkit -- login --token <token>\`.
|
|
360
|
-
5. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`.
|
|
361
|
-
6. Run \`npm run agentkit -- deploy\`.
|
|
362
|
-
7. Run \`npm run agentkit -- chat-ui --deploy\` to test the hosted agent through a local UI using the auto-created \`.agentkit/chat-access-token.json\`. Create extra client-facing deploy access tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
|
|
363
|
-
8. Use \`npm run agentkit -- deploy --smoke "hello"\` during deploy or \`npm run agentkit -- deploy smoke --message "hello"\` afterward for an official hosted smoke check.
|
|
364
|
-
|
|
365
|
-
AgentKit owns hosted infrastructure and production secrets. Do not put production secret values in this capsule. Do not run operator/admin commands from a user capsule.
|
|
366
279
|
`,
|
|
367
280
|
},
|
|
368
281
|
{
|
|
@@ -404,14 +317,14 @@ When a real provider or tool needs a local development secret, keep the required
|
|
|
404
317
|
|
|
405
318
|
\`npm run dev\` runs the whole capsule locally. It should expose local chat, API, inspect, and storage endpoints.
|
|
406
319
|
|
|
407
|
-
For UI testing, run \`npm run dev\` and open the printed \`Chat:\` URL.
|
|
320
|
+
For UI testing, run \`npm run dev\` and open the printed \`Chat:\` URL.
|
|
408
321
|
|
|
409
322
|
\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider before real model behavior is tested.
|
|
410
323
|
|
|
411
324
|
## Files
|
|
412
325
|
|
|
413
326
|
- \`agentkit.config.ts\`: agent contract.
|
|
414
|
-
- \`schema.sql\`: source of truth for agent-owned tables. Applied
|
|
327
|
+
- \`schema.sql\`: source of truth for agent-owned tables. Applied to the local SQLite database.
|
|
415
328
|
- \`prompts/instructions.md\`: agent instructions.
|
|
416
329
|
- \`evals/\`: eval cases.
|
|
417
330
|
- \`.agentkit/\`: local runtime state.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import type { AgentTemplateContext, TemplateFile } from ".";
|
|
2
|
+
|
|
3
|
+
export function commonTemplateFiles(projectName: string, context: AgentTemplateContext): TemplateFile[] {
|
|
4
|
+
return [
|
|
5
|
+
{
|
|
6
|
+
path: "package.json",
|
|
7
|
+
contents: `${JSON.stringify(
|
|
8
|
+
{
|
|
9
|
+
name: projectName,
|
|
10
|
+
private: true,
|
|
11
|
+
type: "module",
|
|
12
|
+
scripts: {
|
|
13
|
+
agentkit: "agentkit",
|
|
14
|
+
dev: "agentkit dev",
|
|
15
|
+
chat: "agentkit chat",
|
|
16
|
+
eval: "agentkit eval run",
|
|
17
|
+
typecheck: "tsc --noEmit",
|
|
18
|
+
},
|
|
19
|
+
dependencies: {
|
|
20
|
+
"@andreprado/agentkit": context.agentkitDependency ?? "workspace:*",
|
|
21
|
+
},
|
|
22
|
+
devDependencies: {
|
|
23
|
+
"@types/node": "^24.12.4",
|
|
24
|
+
typescript: "^5.9.3",
|
|
25
|
+
},
|
|
26
|
+
},
|
|
27
|
+
null,
|
|
28
|
+
2,
|
|
29
|
+
)}
|
|
30
|
+
`,
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
path: "tsconfig.json",
|
|
34
|
+
contents: `${JSON.stringify(
|
|
35
|
+
{
|
|
36
|
+
compilerOptions: {
|
|
37
|
+
target: "ES2022",
|
|
38
|
+
module: "ESNext",
|
|
39
|
+
moduleResolution: "Bundler",
|
|
40
|
+
strict: true,
|
|
41
|
+
skipLibCheck: true,
|
|
42
|
+
noEmit: true,
|
|
43
|
+
types: ["node"],
|
|
44
|
+
},
|
|
45
|
+
include: ["**/*.ts"],
|
|
46
|
+
},
|
|
47
|
+
null,
|
|
48
|
+
2,
|
|
49
|
+
)}
|
|
50
|
+
`,
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
path: ".gitignore",
|
|
54
|
+
contents: `.env
|
|
55
|
+
.agentkit/
|
|
56
|
+
node_modules/
|
|
57
|
+
`,
|
|
58
|
+
},
|
|
59
|
+
];
|
|
60
|
+
}
|
|
@@ -1,63 +1,11 @@
|
|
|
1
1
|
import type { AgentTemplate } from ".";
|
|
2
|
+
import { commonTemplateFiles } from "./common";
|
|
2
3
|
|
|
3
4
|
export const dentistaTemplate: AgentTemplate = {
|
|
4
5
|
name: "dentista",
|
|
5
6
|
files(projectName: string, context = {}) {
|
|
6
7
|
return [
|
|
7
|
-
|
|
8
|
-
path: "package.json",
|
|
9
|
-
contents: `${JSON.stringify(
|
|
10
|
-
{
|
|
11
|
-
name: projectName,
|
|
12
|
-
private: true,
|
|
13
|
-
type: "module",
|
|
14
|
-
scripts: {
|
|
15
|
-
agentkit: "agentkit",
|
|
16
|
-
dev: "agentkit dev",
|
|
17
|
-
chat: "agentkit chat",
|
|
18
|
-
eval: "agentkit eval run",
|
|
19
|
-
typecheck: "tsc --noEmit",
|
|
20
|
-
},
|
|
21
|
-
dependencies: {
|
|
22
|
-
"@andreprado/agentkit": context.agentkitDependency ?? "workspace:*",
|
|
23
|
-
},
|
|
24
|
-
devDependencies: {
|
|
25
|
-
"@types/node": "^24.12.4",
|
|
26
|
-
typescript: "^5.9.3",
|
|
27
|
-
},
|
|
28
|
-
},
|
|
29
|
-
null,
|
|
30
|
-
2,
|
|
31
|
-
)}
|
|
32
|
-
`,
|
|
33
|
-
},
|
|
34
|
-
{
|
|
35
|
-
path: "tsconfig.json",
|
|
36
|
-
contents: `${JSON.stringify(
|
|
37
|
-
{
|
|
38
|
-
compilerOptions: {
|
|
39
|
-
target: "ES2022",
|
|
40
|
-
module: "ESNext",
|
|
41
|
-
moduleResolution: "Bundler",
|
|
42
|
-
strict: true,
|
|
43
|
-
skipLibCheck: true,
|
|
44
|
-
noEmit: true,
|
|
45
|
-
types: ["node"],
|
|
46
|
-
},
|
|
47
|
-
include: ["**/*.ts"],
|
|
48
|
-
},
|
|
49
|
-
null,
|
|
50
|
-
2,
|
|
51
|
-
)}
|
|
52
|
-
`,
|
|
53
|
-
},
|
|
54
|
-
{
|
|
55
|
-
path: ".gitignore",
|
|
56
|
-
contents: `.env
|
|
57
|
-
.agentkit/
|
|
58
|
-
node_modules/
|
|
59
|
-
`,
|
|
60
|
-
},
|
|
8
|
+
...commonTemplateFiles(projectName, context),
|
|
61
9
|
{
|
|
62
10
|
path: ".env.schema",
|
|
63
11
|
contents: `# Opcional: adicione chaves reais depois de trocar o provider test/fake.
|
|
@@ -79,7 +27,7 @@ import {
|
|
|
79
27
|
|
|
80
28
|
export default defineAgent({
|
|
81
29
|
name: "Clara",
|
|
82
|
-
runtime: "
|
|
30
|
+
runtime: "local",
|
|
83
31
|
provider: {
|
|
84
32
|
name: "test",
|
|
85
33
|
model: "fake",
|
|
@@ -95,7 +43,7 @@ export default defineAgent({
|
|
|
95
43
|
driver: "agentkit",
|
|
96
44
|
path: ".agentkit/agentkit.db",
|
|
97
45
|
database: {
|
|
98
|
-
driver: "
|
|
46
|
+
driver: "sqlite",
|
|
99
47
|
schema: "./schema.sql",
|
|
100
48
|
},
|
|
101
49
|
},
|
|
@@ -878,7 +826,7 @@ Não edite apenas o prompt. Para cada requisito relevante do pedido ou do \`AGEN
|
|
|
878
826
|
- schema/migration mais ferramenta para dados duráveis;
|
|
879
827
|
- eval para privacidade, confirmação, campos obrigatórios, horário comercial, datas, duração e regressões;
|
|
880
828
|
- fixture, seed, branch fake ou teste direto de ferramenta para integrações e caminhos de erro;
|
|
881
|
-
- checagem de
|
|
829
|
+
- checagem de configuração local, secrets e ferramentas externas.
|
|
882
830
|
|
|
883
831
|
Regras que protegem privacidade, agendamento, confirmação, dados de cliente, horário comercial ou segurança precisam de eval ou checagem determinística antes de dizer que a cápsula está pronta. Se uma conversa real revelar bug, transforme em uma eval de regressão pequena antes ou junto da correção.
|
|
884
832
|
|
|
@@ -921,7 +869,6 @@ Regras que protegem privacidade, agendamento, confirmação, dados de cliente, h
|
|
|
921
869
|
## Teste Com UI
|
|
922
870
|
|
|
923
871
|
- UI local: rode \`npm run dev\`, abra a URL impressa em \`Chat:\` e informe essa URL exata ao dono.
|
|
924
|
-
- UI pós-deploy: depois de \`npm run agentkit -- deploy\`, rode \`npm run agentkit -- chat-ui --deploy\`, abra a URL impressa em \`Chat:\` e informe que ela está conectada ao deploy hospedado.
|
|
925
872
|
- \`test/fake\` é determinístico. Ele valida scaffold, ferramentas e evals previsíveis, mas não valida qualidade de conversa natural.
|
|
926
873
|
- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono.
|
|
927
874
|
|
|
@@ -935,7 +882,7 @@ Regras que protegem privacidade, agendamento, confirmação, dados de cliente, h
|
|
|
935
882
|
- Transforme conversas reais com falhas em regressão com \`npm run agentkit -- eval from-conversation <conversation-id>\`.
|
|
936
883
|
- Mantenha segredos em \`.env\`, nunca em arquivos versionados.
|
|
937
884
|
- Não espere wizard ou recipe. AgentKit fornece o scaffold e o contrato; implemente diretamente conforme o brief do dono.
|
|
938
|
-
- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais
|
|
885
|
+
- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais.
|
|
939
886
|
- Quando a próxima ação não for óbvia, comece por \`skills/agentkit-capsule/SKILL.md\`.
|
|
940
887
|
`,
|
|
941
888
|
},
|
|
@@ -1004,24 +951,10 @@ npm run dev
|
|
|
1004
951
|
|
|
1005
952
|
Abra a URL impressa em \`Chat:\` e informe essa URL exata ao dono.
|
|
1006
953
|
|
|
1007
|
-
UI pós-deploy:
|
|
1008
|
-
|
|
1009
|
-
\`\`\`sh
|
|
1010
|
-
npm run agentkit -- deploy
|
|
1011
|
-
npm run agentkit -- chat-ui --deploy
|
|
1012
|
-
\`\`\`
|
|
1013
|
-
|
|
1014
|
-
Abra a URL impressa em \`Chat:\` e informe que essa UI local está conectada ao deploy hospedado.
|
|
1015
954
|
|
|
1016
|
-
Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
|
|
1017
955
|
|
|
1018
|
-
|
|
956
|
+
Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais.
|
|
1019
957
|
|
|
1020
|
-
- A cápsula começa com o provider \`test/fake\`, então roda localmente sem chaves.
|
|
1021
|
-
- Para produção ou teste real de conversa, o dono deve escolher o provider real antes da troca.
|
|
1022
|
-
- Guarde chaves em segredos gerenciados ou em \`.env\` local ignorado pelo git.
|
|
1023
|
-
- Use \`npm run agentkit -- deploy doctor\` antes de publicar.
|
|
1024
|
-
- Use \`npm run agentkit -- deploy --smoke "Oi"\` durante o deploy ou \`npm run agentkit -- deploy smoke --message "Oi"\` depois para um smoke oficial do chat hospedado.
|
|
1025
958
|
`,
|
|
1026
959
|
},
|
|
1027
960
|
];
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentkit-capsule
|
|
3
|
-
description: Use when working inside an AgentKit Agent Capsule, especially after detecting agentkit.config.ts or when the owner asks to build, change,
|
|
3
|
+
description: Use when working inside an AgentKit Agent Capsule, especially after detecting agentkit.config.ts or when the owner asks to build, change, or test an AgentKit agent. Routes to task-specific AgentKit skills while avoiding loading the full docs by default.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# AgentKit Capsule
|
|
@@ -14,7 +14,7 @@ The owner has already done the setup work by running `agentkit new [name]` or `a
|
|
|
14
14
|
- Do not ask the owner to run a wizard, fill a form, or prepare `AGENT_SPEC.md`.
|
|
15
15
|
- Route immediately to `skills/agentkit-build-agent/SKILL.md`.
|
|
16
16
|
- You create or update `AGENT_SPEC.md`, prompts, tools, schema, evals, and docs as needed.
|
|
17
|
-
- Use the CLI for validation
|
|
17
|
+
- Use the CLI for validation, not for business inference.
|
|
18
18
|
|
|
19
19
|
## Proactive Builder Contract
|
|
20
20
|
|
|
@@ -24,7 +24,7 @@ Do not stop at "the prompt was edited." For every meaningful requirement in the
|
|
|
24
24
|
- action, live data, or external write: `tools/` plus `agentkit.config.ts`;
|
|
25
25
|
- durable records: schema/migration, tool, config registration, prompt guidance, direct tool check, and eval;
|
|
26
26
|
- privacy, confirmation, business hours, dates, money, safety, or client data: at least one eval or deterministic check;
|
|
27
|
-
- production or integration dependency:
|
|
27
|
+
- production or integration dependency: local config and secret check and safe fixture or fake path.
|
|
28
28
|
|
|
29
29
|
If a real conversation reveals a bug or risky behavior, convert it into a regression eval before or alongside the fix.
|
|
30
30
|
|
|
@@ -40,13 +40,11 @@ If a real conversation reveals a bug or risky behavior, convert it into a regres
|
|
|
40
40
|
- Build or reshape the agent from the owner's brief: `skills/agentkit-build-agent/SKILL.md`
|
|
41
41
|
- Edit prompts: `skills/agentkit-prompts/SKILL.md`
|
|
42
42
|
- Add actions, external data, or TypeSafe/Jev judgments: `skills/agentkit-tools/SKILL.md`
|
|
43
|
-
- Add AgentKit-managed integrations such as managed Composio: `skills/agentkit-integrations/SKILL.md`
|
|
44
43
|
- Add database tables or database-backed tools: `skills/agentkit-database/SKILL.md`
|
|
45
44
|
- Add docs, FAQs, prices, policies, or CSV facts: `skills/agentkit-knowledge/SKILL.md`
|
|
46
45
|
- Switch from `test/fake` to a real model provider: `skills/agentkit-provider/SKILL.md`
|
|
47
46
|
- Add or run evals: `skills/agentkit-evals/SKILL.md`
|
|
48
|
-
- Improve from
|
|
49
|
-
- Prepare hosted deploy: `skills/agentkit-deploy/SKILL.md`
|
|
47
|
+
- Improve from local production evidence: `skills/agentkit-improve/SKILL.md`
|
|
50
48
|
- Work with secrets, external APIs, public access, channels, or real data: `skills/agentkit-security/SKILL.md`
|
|
51
49
|
- Add or debug website, Telegram, WhatsApp, Discord, Slack, or generic webhook channels: `skills/agentkit-channels/SKILL.md`
|
|
52
50
|
- Investigate command failures: `skills/agentkit-troubleshooting/SKILL.md`
|
|
@@ -84,7 +82,7 @@ npm run agentkit -- replay .agentkit/improve/<run> --against local
|
|
|
84
82
|
## Rules
|
|
85
83
|
|
|
86
84
|
- Keep `.env`, `.agentkit/`, and `node_modules/` out of commits.
|
|
87
|
-
- Keep secret names in `.env.schema`; keep secret values in ignored `.env
|
|
85
|
+
- Keep secret names in `.env.schema`; keep secret values in ignored `.env`.
|
|
88
86
|
- Keep the first useful version runnable with `test/fake` unless the owner explicitly chooses a real provider.
|
|
89
87
|
- For scheduling or relative-date agents, set `timeZone` in `agentkit.config.ts`; AgentKit injects the current date, weekday, timestamp, and timezone dynamically at runtime.
|
|
90
88
|
- Ask follow-up questions only when missing information blocks a safe local implementation.
|
|
@@ -4,11 +4,10 @@ Prefer the narrowest source that covers the task.
|
|
|
4
4
|
|
|
5
5
|
- Capsule creation and scaffold verification: `docs/guides/create-agent.md`
|
|
6
6
|
- Tools, schemas, secrets, and direct tool tests: `docs/guides/add-tool.md`
|
|
7
|
-
- Knowledge sources, indexing, search
|
|
7
|
+
- Knowledge sources, indexing, search,: `docs/guides/add-knowledge.md`
|
|
8
8
|
- Evals and deterministic side-effect guards: `docs/guides/run-evals.md`
|
|
9
|
-
- Safe AgentKit product feedback drafts/submission: `docs/guides/
|
|
9
|
+
- Safe AgentKit product feedback drafts/submission: `docs/guides/write-feedback.md`
|
|
10
10
|
- Real provider setup: `docs/guides/use-provider.md`
|
|
11
|
-
- Deploy readiness, managed secrets, smoke checks, hosted UI: `docs/guides/prepare-deploy.md`
|
|
12
11
|
- Channels: `docs/guides/add-channel.md`, `connect-discord.md`, `connect-slack.md`, `connect-telegram.md`, `connect-whatsapp-evolution.md`, `connect-whatsapp-uazapi.md`, `connect-whatsapp-zapster.md`, `debug-channel.md`
|
|
13
12
|
- Security: `docs/guides/security-rules.md`
|
|
14
13
|
|