Quick Start

This guide gets you from zero to a working AI agent in under 5 minutes.

1. Create a project

npx tutti-ai init my-agent
cd my-agent
npm install

2. Add your API key

cp .env.example .env

Edit .env and paste your Anthropic API key:

ANTHROPIC_API_KEY=sk-ant-your-key-here

3. Edit your score

Open tutti.score.ts — this is already generated for you:

import { AnthropicProvider, defineScore } from "@tuttiai/core";

export default defineScore({
  name: "my-agent",
  provider: new AnthropicProvider(),
  agents: {
    assistant: {
      name: "assistant",
      model: "claude-sonnet-4-20250514",
      system_prompt:
        "You are a helpful assistant. Answer clearly and concisely.",
      voices: [],
    },
  },
});

4. Run it

npx tutti-ai run

You’ll see the Tutti REPL:

Tutti REPL — type "exit" to quit

> What is the capital of France?

Running agent: assistant

The capital of France is Paris.

>

Type exit (or Ctrl+C) to leave.

One-shot mode

Skip the REPL entirely — run a single prompt and get the answer back on stdout. Great for scripts and pipelines:

$ npx tutti-ai run -p "What is the capital of France?"
The capital of France is Paris.

5. Add tools

Let’s give the agent filesystem access:

npx tutti-ai add filesystem

Update your score:

import { AnthropicProvider, defineScore } from "@tuttiai/core";
import { FilesystemVoice } from "@tuttiai/filesystem";

export default defineScore({
  name: "my-agent",
  provider: new AnthropicProvider(),
  agents: {
    assistant: {
      name: "assistant",
      model: "claude-sonnet-4-20250514",
      system_prompt: "You are a helpful assistant with filesystem access.",
      voices: [new FilesystemVoice()],
      permissions: ["filesystem"],
    },
  },
});

Now run it again:

> Create a file called hello.txt with "Hello from Tutti!"

Running agent: assistant
  Using tool: write_file
  Done: write_file

Done! I created hello.txt with the content "Hello from Tutti!".

Next steps

• Core Concepts — understand agents, voices, and scores
• Multi-Agent Orchestration — delegate between specialist agents
• Security — permissions, budgets, and secret management