@ideascol/agents-generator-sdk 0.7.4 → 0.8.0

package/README.md

@@ -135,6 +135,193 @@ interface StreamCallbacks {
 }
 ```
 
+## Inline agents (Genkit-style, no persistence)
+
+Define an agent in code and execute it without persisting the configuration
+on the platform. The full agent definition travels in each request.
+
+Two distinct credentials — do not confuse them:
+
+- **`apiToken`** (constructor) — platform auth. A Keycloak JWT or a workspace
+  API key (`ack_*`). Optional. When omitted, the SDK runs in **anonymous
+  mode** and the backend skips workspace context.
+- **`apiKey`** (`defineAgent`) — model-provider credential (OpenAI key, etc.).
+  Travels in the request body as `api_key`. Required in anonymous mode.
+
+Anonymous mode rejects: `credentialId` references (agent or per-node) and
+`workspaceAgentTool` nodes — both need workspace scoping.
+
+### Minimal — anonymous, no tools
+
+```ts
+import { AgentClient } from '@ideascol/agents-generator-sdk';
+
+const client = new AgentClient({
+  apiUrl: 'http://localhost:8000',
+  // no apiToken → anonymous mode
+});
+
+const agent = client.defineAgent({
+  name: 'haiku-bot',
+  instructions: 'Write short, original haikus on the topic the user gives.',
+  modelProvider: 'openai',     // autocompletes 75 providers
+  modelName: 'gpt-5-mini',     // autocompletes 2050 models
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const r = await agent.run('the sea at dawn');
+console.log(r.message);
+```
+
+### With local function tools
+
+The SDK runs the callback-tool loop transparently: it executes your local
+handler when the model calls the tool and posts the result back to continue
+the same logical turn.
+
+```ts
+const agent = client.defineAgent({
+  name: 'weather',
+  instructions: 'Use get_weather to answer questions.',
+  modelProvider: 'openai',
+  modelName: 'gpt-5-mini',
+  apiKey: process.env.OPENAI_API_KEY,
+  maxToolIterations: 10,        // cap on tool round-trips per run
+  functions: [
+    {
+      name: 'get_weather',
+      description: 'Return current weather for a city.',
+      parameters: {
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+      },
+      execute: async ({ city }: { city: string }) => ({
+        city,
+        temp_c: 22,
+        conditions: 'sunny',
+      }),
+    },
+  ],
+});
+
+const r = await agent.run('Weather in Bogota?');
+console.log(r.message);
+console.log('tool calls:', r.tool_results?.length);
+```
+
+### Stateless with prior history
+
+The SDK replays full history on each request — fine for short sessions,
+prefer ephemeral conversations beyond ~20 turns.
+
+```ts
+import { InlineMessage } from '@ideascol/agents-generator-sdk';
+
+const history: InlineMessage[] = [
+  { role: 'user', content: 'My name is Jairo.' },
+  { role: 'assistant', content: 'Nice to meet you, Jairo.' },
+];
+const r = await agent.run("What's my name?", { history });
+```
+
+### SSE streaming — callbacks
+
+```ts
+let prev = 0;
+await agent.run('write a 6-sentence story about a robot in a forest', {
+  callbacks: {
+    onMessage: (content) => {
+      process.stdout.write(content.slice(prev));
+      prev = content.length;
+    },
+    onToolCall: (tc) => console.log('\n[tool]', tc.name),
+    onDone: () => console.log('\n[done]'),
+    onError: (err) => console.error(err.message),
+  },
+});
+```
+
+### SSE streaming — AsyncIterable
+
+```ts
+let prev = '';
+for await (const ev of agent.runStream('tell me a joke')) {
+  if (ev.type === 'message' && typeof (ev as any).content === 'string') {
+    const c = (ev as any).content as string;
+    process.stdout.write(c.slice(prev.length));
+    prev = c;
+  } else if (ev.type === 'done') {
+    break;
+  }
+}
+```
+
+### Ephemeral conversation (multi-turn, server-tracked, TTL)
+
+The backend keeps state for the session under a TTL'd row. No need to
+replay history on each turn. Send messages via the returned handle.
+
+```ts
+const conv = await agent.startConversation({ ttlSeconds: 600 });
+console.log('conversation_id:', conv.conversation_id);
+
+await conv.send('My favorite color is teal.');
+const r2 = await conv.send("What's my favorite color?");
+console.log(r2.message);   // → "Your favorite color is teal."
+
+await conv.close();        // best-effort DELETE
+```
+
+### Authenticated mode (workspace credential reference)
+
+Pass an `ack_*` workspace API key as `apiToken` to unlock workspace-scoped
+features: stored credentials, workspace-agent tools, token-usage tracking.
+
+```ts
+const client = new AgentClient({
+  apiUrl: 'https://api.agentsgenerator.dev',
+  apiToken: 'ack_xxx',  // create one in the platform UI → Workspace → API Keys
+});
+
+const agent = client.defineAgent({
+  name: 'support',
+  instructions: '...',
+  modelProvider: 'openai',
+  modelName: 'gpt-5-mini',
+  credentialId: 'cred-uuid',  // resolves against the workspace
+});
+await agent.run('hello');
+```
+
+### Typed model catalog
+
+`ModelProvider` / `ModelName` literal unions provide autocomplete on
+`modelProvider` and `modelName`. Custom strings still allowed (forward-compat).
+Snapshot is regeneratable from the live backend:
+
+```ts
+import {
+  MODELS_BY_PROVIDER,
+  MODEL_INFO,
+  type ModelProvider,
+  type ModelName,
+} from '@ideascol/agents-generator-sdk';
+
+console.log(MODELS_BY_PROVIDER.anthropic);                // ["claude-...", ...]
+console.log(MODEL_INFO['gpt-5-mini'].max_input_tokens);   // number
+```
+
+Regenerate the snapshot:
+
+```bash
+API_URL=https://api.agentsgenerator.dev bun run generate:models
+# or against a local backend:
+API_URL=http://localhost:8000 bun run generate:models
+# filters:
+MODELS_MODE=chat MODELS_FN_CALLING=true bun run generate:models
+```
+
 ## Quick start
 ```bash
 # Using npm