# Getting Started

> Install Struere and create your first agent


## Prerequisites

Before you begin, make sure you have:

- **Node.js 18+** installed
- **Bun** installed (`curl -fsSL https://bun.sh/install | bash`) — used as the package manager
- A **Struere account** — sign up at [app.struere.dev](https://app.struere.dev)
- An **LLM provider** — either use Struere's built-in credits or bring your own API key (configured in **Settings > Providers** in the dashboard)

## Quick Start with a Coding Agent

If you use Claude Code, Cursor, or another AI coding agent, copy this prompt to bootstrap your project instantly:

```
I want to set up a Struere project (https://struere.dev) — an AI agent platform where I define agents, data types, roles, and automations as TypeScript code.

## Environment Setup

Before running any commands, ensure bun is in your PATH:
  export PATH="$HOME/.bun/bin:$PATH"

If `bun --version` still fails, install bun first:
  curl -fsSL https://bun.sh/install | bash

## Step 1: Install the Struere CLI
  bun install -g struere

## Step 2: Authenticate and initialize the project
First, ensure a fresh login (logout first to clear any stale tokens):
  struere logout
  struere login
(This opens a browser — wait for me to complete the login)

Then initialize the project:
  struere init
(This will ask me to select an organization if I have more than one — let me choose)

Then pull any existing configurations:
  struere pull

## Step 3: Install the Struere developer skill
Run: npx skills add MarcoNaik/struere-skill --all --yes
If npx is not found, try: $HOME/.bun/bin/bunx skills add MarcoNaik/struere-skill --all --yes

After completing these steps, show me the project structure and summarize what was set up. If any step fails, show me the error and suggest a fix.

Documentation: https://docs.struere.dev/llms.txt
```

This single prompt handles authentication, project setup, and skill installation. The developer skill teaches your coding agent how to use Struere's SDK, avoid common mistakes, and fetch the right documentation.

If you prefer to set things up manually, continue with the steps below.

## Installation

Install the Struere package as a project dependency:

```bash
npm install struere
```

## Initialize a Project

Run the init command to scaffold an organization-centric project:

```bash
npx struere init
```

This command will:

1. Open a browser for authentication (sign in with your Struere account)
2. Prompt you to select an organization
3. Create the project directory structure
4. Write a `struere.json` configuration file with your organization details
5. Generate `.struere/types.d.ts` for type definitions

### Project Structure

After initialization, your project will have this structure:

```
my-org/
├── struere.json
├── agents/
│   └── (your agent definitions)
├── entity-types/
│   └── (your data type schemas)
├── roles/
│   └── (your role definitions with policies)
├── triggers/
│   └── (your automations)
├── tools/
│   └── index.ts
├── evals/
│   └── (your eval suites as YAML)
└── fixtures/
    └── (your test data for evals as YAML)
```

### struere.json

The configuration file identifies your organization:

```json
{
  "version": "2.0",
  "organization": {
    "id": "org_abc123",
    "slug": "acme-corp",
    "name": "Acme Corp"
  }
}
```

## Create Your First Agent

Create a file at `agents/my-agent.ts`:

```typescript
import { defineAgent } from 'struere'

export default defineAgent({
  name: "My First Agent",
  slug: "my-first-agent",
  version: "0.1.0",
  systemPrompt: "You are a helpful assistant for {{organizationName}}. Current time: {{currentTime}}.",
  model: {
    model: "openai/gpt-5-mini",
  },
  tools: ["entity.query"],
})
```

This defines an agent that:
- Uses Grok 4.1 Fast as its LLM
- Has access to query entities
- Receives the organization name and current time in its system prompt via template variables

## Define a Data Type

Create a file at `entity-types/customer.ts`:

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Customer",
  slug: "customer",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      email: { type: "string", format: "email" },
      plan: { type: "string", enum: ["free", "pro", "enterprise"] },
    },
    required: ["name", "email"],
  },
  searchFields: ["name", "email"],
})
```

## Define a Role

Create a file at `roles/support.ts`:

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "support",
  description: "Support agents with read access to customers",
  policies: [
    { resource: "customer", actions: ["list", "read"], effect: "allow" },
    { resource: "customer", actions: ["delete"], effect: "deny" },
  ],
})
```

## Start Development

Run the dev command to sync your definitions to the platform:

```bash
npx struere dev
```

You should see output like:

```
✓ Logged in as you@example.com
✓ Loaded 1 agent, 1 data type, 1 role, 0 automations
✓ Synced to development environment
  Watching for changes...
```

The `dev` command will:

1. Auto-login if you are not authenticated (opens a browser)
2. Load all resource definitions from `agents/`, `entity-types/`, `roles/`, `triggers/`, `tools/`, `evals/`, and `fixtures/`
3. Sync to the **development** environment (agents, types, roles, triggers) and the **eval** environment (agents, types, roles, eval suites, fixtures)
4. Watch for file changes and re-sync automatically

Every time you save a file, the CLI re-syncs your changes.

## Test Your Agent

Once synced, you can interact with your agent in two ways:

### Via the API

Create an API key in the dashboard under **Settings > API Keys**. Select the **development** environment.

Then send a request using the slug-based endpoint:

```bash
curl -X POST https://api.struere.dev/v1/agents/my-first-agent/chat \
  -H "Authorization: Bearer sk_dev_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'
```

You should receive a JSON response:

```json
{
  "threadId": "jd7abc123...",
  "message": "Hello! I'm your assistant for Acme Corp. I can query your data and log events. How can I help?",
  "usage": {
    "inputTokens": 245,
    "outputTokens": 32,
    "totalTokens": 277
  }
}
```

Your API URL is shown in the dashboard under **Settings > API Keys**.

### Via the Dashboard

1. Open [app.struere.dev](https://app.struere.dev) and navigate to **Agents**
2. Select your agent ("My First Agent")
3. Use the built-in chat interface to send a message

## Deploy to Production

When you are ready to go live, deploy your agents to the production environment:

```bash
npx struere deploy
```

This promotes all agent configurations to the production environment where they are accessible via production API keys (prefixed `sk_prod_`).

## Next Steps

- [Chat API](./api/chat) — Full API reference for sending messages to agents
- [CLI Overview](./cli/overview) — Learn all available CLI commands
- [Agent Configuration](./sdk/define-agent) — Configure models, tools, and system prompts
- [Data Types](./sdk/define-data) — Define structured data schemas
- [Built-in Tools](./tools/built-in-tools) — All available agent tools
- [Automations](./sdk/define-trigger) — Build event-driven automations