{
  "uid": "cogitave.learn.docs.quickstart",
  "kind": "doc",
  "href": "/docs/quickstart/",
  "title": "Quickstart - run your first agent",
  "summary": "Install the Namzu kernel and one provider, send a first message, and see the shape of a response. Local-first with Ollama, no account and no hosted service required.",
  "type": "tutorial",
  "products": [
    "namzu"
  ],
  "roles": [
    "developer"
  ],
  "levels": [
    "beginner"
  ],
  "subjects": [],
  "headings": [
    "Before you start",
    "1. Install the kernel and a provider",
    "2. Register the provider and send a message",
    "3. Read the response",
    "4. Swap the vendor without touching your code",
    "What you have now",
    "Next steps"
  ],
  "source": "\n# Quickstart - run your first agent\n\nThis is the shortest path from nothing to a working agent call. It runs locally,\nneeds no account, and takes about five minutes.\n\nIf you would rather understand the model before you use it, read\n[What Namzu is](what-is-namzu.md) first. If you want a guided course with\nexercises, take the [training](/training/) instead - this page is a quickstart,\nnot a lesson.\n\n## Before you start\n\n- **Node.js 20 or later** and a package manager. The examples use `pnpm`.\n- **TypeScript 5.5 or later** if you are writing TypeScript.\n- For the local path: [Ollama](https://ollama.com) running on\n  `http://localhost:11434` with one model pulled.\n\nYou do not need a cloud key for this quickstart. Ollama is the zero-config,\nlocal-first default.\n\n## 1. Install the kernel and a provider\n\nThe kernel and the provider drivers are separate packages, so you install\nexactly one vendor:\n\n```bash\npnpm add @namzu/sdk @namzu/ollama\n```\n\n> [!NOTE]\n> Installed on its own, `@namzu/sdk` runs against a pre-registered\n> `MockLLMProvider` with no network dependency. That is the right default for\n> tests - you can write and run the whole flow before choosing a vendor.\n\n## 2. Register the provider and send a message\n\n```typescript\nimport { ProviderRegistry, createUserMessage, collect } from '@namzu/sdk'\nimport { registerOllama } from '@namzu/ollama'\n\n// Register once, at startup.\nregisterOllama()\n\nconst { provider } = ProviderRegistry.create({\n  type: 'ollama',\n  host: 'http://localhost:11434',\n})\n\n// The provider's single entry point is a stream. `collect` drains it into one\n// aggregated response when you want the whole answer rather than per-token deltas.\nconst response = await collect(\n  provider.chatStream({\n    model: 'llama3.2',\n    messages: [createUserMessage('What is the capital of France?')],\n  }),\n)\n\nconsole.log(response.message.content)\n```\n\n## 3. Read the response\n\nEvery provider returns the same shape, whichever vendor produced it:\n\n```typescript\n{\n  id: string,\n  model: string,\n  message: { role, content, toolCalls? },\n  finishReason: string,\n  usage: { /* token counts */ }\n}\n```\n\nThat uniformity is the point of the kernel: the code below the registration line\ndoes not know or care which vendor answered.\n\n## 4. Swap the vendor without touching your code\n\nChanging provider is a change to the registration, not to your agent:\n\n```typescript\nimport { registerOpenAI } from '@namzu/openai'      // registerOpenAI()\nimport { registerAnthropic } from '@namzu/anthropic' // registerAnthropic()\nimport { registerBedrock } from '@namzu/bedrock'     // registerBedrock()\n```\n\nEverything after registration stays identical. See\n[Choose a provider](choose-a-provider.md) for the full list and the trade-offs.\n\n## What you have now\n\nA local agent call through a vendor-neutral kernel, with a response shape that\nwill not change when you move to a hosted model.\n\n## Next steps\n\n- [Choose a provider](choose-a-provider.md) - the eight drivers and when each fits.\n- [Check your environment](check-your-environment.md) - what `namzu doctor` verifies.\n- [What Namzu is](what-is-namzu.md) - the kernel model, and what is deliberately\n  not in it.\n- [Packages](packages.md) - the full published surface.\n",
  "lastReviewed": "2026-07-26",
  "order": 1
}