# Quick Start

URL: https://cogitator.app/docs/getting-started/quick-start

> Build your first AI agent in 5 minutes.

## Your First Agent

Create a file `src/agent.ts`:

```typescript
import { Cogitator, Agent } from '@cogitator-ai/core';

const cogitator = new Cogitator({
  llm: {
    providers: {
      ollama: { baseUrl: 'http://localhost:11434' },
    },
  },
});

const assistant = new Agent({
  name: 'assistant',
  model: 'ollama/llama3.2',
  instructions: 'You are a helpful assistant. Be concise and friendly.',
});

const result = await cogitator.run(assistant, { input: 'Hello! What can you help me with?' });

console.log('Agent:', result.output);
console.log('Tokens:', result.usage.totalTokens);

await cogitator.close();
```

Run it (with Ollama running and `ollama pull llama3.2` done):

```bash
npx tsx src/agent.ts
```

`run()` takes the agent and a `RunOptions` object; `input` is the user message. The result carries the answer in `output`, token counts and cost in `usage`, every tool call in `toolCalls` and the run's spans in `trace`.

## Adding Tools

Tools give your agent the ability to take actions. Define them with Zod schemas for full type safety:

```typescript
import { Cogitator, Agent, tool } from '@cogitator-ai/core';
import { z } from 'zod';

const getWeather = tool({
  name: 'get_weather',
  description: 'Get the current weather for a city',
  parameters: z.object({
    city: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  execute: async ({ city, units }) => ({
    city,
    temperature: units === 'celsius' ? 22 : 72,
    condition: 'sunny',
  }),
});

const weatherBot = new Agent({
  name: 'weather-bot',
  model: 'ollama/llama3.2',
  instructions: 'You are a weather assistant. Use the get_weather tool to answer questions.',
  tools: [getWeather],
});

const cogitator = new Cogitator();

const result = await cogitator.run(weatherBot, { input: 'What is the weather like in Tokyo?' });
console.log(result.output);
console.log(result.toolCalls.map((call) => call.name)); // ['get_weather']
```

Without any configuration, Cogitator talks to Ollama at `http://localhost:11434`.

## Streaming Responses

For real-time output, stream the tokens:

```typescript
const result = await cogitator.run(assistant, {
  input: 'Write a short poem about coding.',
  stream: true,
  onToken: (token) => process.stdout.write(token),
});
```

`result.output` still holds the whole answer once the run finishes.

## Conversations

Runs with the same `threadId` share a conversation when memory is configured:

```typescript
const cogitator = new Cogitator({
  llm: { providers: { ollama: { baseUrl: 'http://localhost:11434' } } },
  memory: { adapter: 'memory' },
});

await cogitator.run(assistant, { input: 'My name is Alex.', threadId: 'chat-1' });
const reply = await cogitator.run(assistant, { input: 'What is my name?', threadId: 'chat-1' });
```

See [Memory](/docs/memory) for persistent adapters.

## Multiple Providers

Configure several LLM providers and route each agent to the model it needs:

```typescript
const cogitator = new Cogitator({
  llm: {
    defaultModel: 'ollama/llama3.2',
    providers: {
      ollama: { baseUrl: 'http://localhost:11434' },
      openai: { apiKey: process.env.OPENAI_API_KEY! },
      anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
    },
  },
});

// runs on llm.defaultModel
const localAgent = new Agent({ name: 'local', instructions: '...' });

// per-agent models
const smartAgent = new Agent({ name: 'smart', instructions: '...', model: 'openai/gpt-6.1-sol' });
const creativeAgent = new Agent({
  name: 'creative',
  instructions: '...',
  model: 'anthropic/claude-sonnet-5-5',
});
```

Model strings:

* `provider/model-name` — routes to that provider (`openai/gpt-6.1-sol`, `google/gemini-3.5-flash-lite`)
* `model-name` — runs on `llm.defaultProvider` (Ollama when unset); so does a string whose prefix is not a known provider, such as `meta-llama/llama-3.3-70b`
* no `model` on the agent — uses `llm.defaultModel`; a run fails with `CONFIGURATION_ERROR` when neither is set

## Next Steps

* [Project Structure](/docs/getting-started/project-structure) — how projects and the monorepo are organized
* [Configuration](/docs/getting-started/configuration) — `cogitator.yml`, environment variables, provider setup
* [Core Concepts](/docs/core/cogitator) — deep dive into the Cogitator runtime