Crystal AI Documentation

npm install @crystralai/sdk

# or with other package managers
pnpm add @crystralai/sdk
yarn add @crystralai/sdk

version: 1
project: my-project

version: 1
name: assistant
provider: openai
model: gpt-4o
system_prompt: |
  You are a helpful assistant. Be concise and accurate.
temperature: 0.7
max_tokens: 4096

OPENAI_API_KEY=sk-your-key-here

import { Crystral } from '@crystralai/sdk';

const client = new Crystral();
const result = await client.run('assistant', 'What is the capital of France?');

console.log(result.content);    // "Paris"
console.log(result.usage.total); // 42
console.log(result.durationMs);  // 823

npx tsx index.ts

my-project/
├── crystral.config.yaml     # Project config (required)
├── agents/                  # Agent YAML definitions
│   └── assistant.yaml
├── tools/                   # Tool YAML definitions
├── workflows/               # Workflow definitions
├── rag/                     # RAG document collections
│   └── my-docs/
├── .crystalai/              # Auto-generated (add to .gitignore)
│   └── agents.db            # SQLite database
├── .env                     # API keys
└── .gitignore

version: 1
name: support-agent
description: Customer support agent
provider: openai
model: gpt-4o
system_prompt: |
  You are a helpful support agent for {company_name}.
  Always be polite and professional.
temperature: 0.3
max_tokens: 2048
tools:
  - get-ticket
  - send-email
rag:
  collections:
    - product-docs
  embedding_provider: openai
  embedding_model: text-embedding-3-small
  match_threshold: 0.75
  match_count: 5

version: 1
name: get-weather
description: Get current weather for a city
type: rest_api
endpoint: https://wttr.in/{city}?format=j1
method: GET
response_path: current_condition.0
parameters:
  - name: city
    type: string
    required: true
    description: City name (e.g. "London")

version: 1
name: calculate
description: Evaluate a math expression
type: javascript
timeout_ms: 5000
parameters:
  - name: expression
    type: string
    required: true
    description: Math expression (e.g. "2 + 2")
code: |
  const result = new Function('return ' + args.expression)();
  return { result: Number(result) };

# Just change these two lines:
provider: anthropic
model: claude-sonnet-4-20250514

rag:
  collections:
    - product-docs
  embedding_provider: openai
  embedding_model: text-embedding-3-small
  match_threshold: 0.7
  match_count: 5

version: 1
name: content-pipeline
description: Research and produce content

orchestrator:
  provider: openai
  model: gpt-4o
  system_prompt: |
    You orchestrate content production.
    Delegate to specialist agents.
  strategy: auto
  max_iterations: 20

agents:
  - name: researcher
    agent: research-agent
    description: Gathers information
  - name: writer
    agent: writing-agent
    description: Writes final content

context:
  shared_memory: true
  max_context_tokens: 8000

const workflow = client.loadWorkflow('content-pipeline');
const result = await workflow.run('Write an article about AI');
console.log(result.content);
console.log(result.agentResults);

mcp:
  - transport: stdio
    name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  - transport: sse
    name: github
    url: http://localhost:3000/mcp

import { Crystral } from '@crystralai/sdk';

const client = new Crystral();

// Single-shot
const result = await client.run('assistant', 'Hello!');
console.log(result.content);

const result = await client.run('assistant', 'Write a haiku.', {
  stream: true,
  onToken: (token) => process.stdout.write(token),
});

const r1 = await client.run('assistant', 'My name is Alice.');
const r2 = await client.run('assistant', 'What is my name?', {
  sessionId: r1.sessionId,
});
// r2.content -> "Your name is Alice."

import { CrystralClient } from '@crystralai/client';

const client = new CrystralClient({
  provider: 'openai',
  model: 'gpt-4o',
  apiKey: userProvidedKey,
  systemPrompt: 'You are a helpful assistant.',
});

const result = await client.run('What is 2+2?');

output:
  format: json
  strict: true
  schema:
    type: object
    required: [summary, items]
    properties:
      summary:
        type: string
      items:
        type: array
        items:
          type: object
          required: [name, score]
          properties:
            name: { type: string }
            score: { type: number }

provider: openai
model: gpt-4o

retry:
  max_attempts: 3
  backoff: exponential
  retry_on:
    - rate_limit
    - server_error
    - timeout

fallback:
  - provider: anthropic
    model: claude-sonnet-4-20250514
  - provider: google
    model: gemini-1.5-pro

guardrails:
  input:
    max_length: 10000
    block_patterns:
      - "(?i)ignore previous instructions"
    pii_action: redact
  output:
    max_length: 5000
    block_patterns:
      - "(?i)internal use only"

cache:
  enabled: true
  ttl: 3600  # seconds