shuttl.core 0.4.1

The JSII library for Shuttl AI models

@shuttl-io/core

A developer-first framework for building, deploying, and managing AI agents. Stop wrestling with complex infrastructure and start shipping intelligent agents in minutes.

Installation

TypeScript/JavaScript:

npm install @shuttl-io/core
# or
pnpm add @shuttl-io/core
# or
yarn add @shuttl-io/core

Python:

pip install shuttl-core

Java (Maven):

<dependency>
  <groupId>io.shuttl.module</groupId>
  <artifactId>core</artifactId>
  <version>0.1.5</version>
</dependency>

Go:

go get github.com/shuttl-io/shuttl-core-go

.NET:

dotnet add package shuttl.core

Quick Start

TypeScript

import { Agent, Model, Secret, Schema } from "@shuttl-io/core";

const weatherTool = {
    name: "get_weather",
    description: "Get current weather for a location",
    schema: Schema.objectValue({
        location: Schema.stringValue("City name").isRequired(),
    }),
    execute: async (args) => {
        return { temperature: 72, condition: "sunny" };
    },
};

export const weatherAgent = new Agent({
    name: "WeatherBot",
    systemPrompt: "You help users check the weather.",
    model: Model.openAI("gpt-4", Secret.fromEnv("OPENAI_KEY")),
    tools: [weatherTool],
});

Python

In Python, tools must be implemented using the @jsii.implements() decorator. Do not inherit directly from the interface - this will cause metaclass conflicts. See the JSII Python documentation for details.

import jsii
from shuttl.core import App, Agent, Model, Secret
from shuttl.core.tools import ITool, ToolArg


@jsii.implements(ITool)
class WeatherTool:
    """A tool that gets weather information."""

    def __init__(self):
        self._name = "get_weather"
        self._description = "Get current weather for a location"

    @property
    def name(self) -> str:
        return self._name

    @name.setter
    def name(self, value: str):
        self._name = value

    @property
    def description(self) -> str:
        return self._description

    @description.setter
    def description(self, value: str):
        self._description = value

    def execute(self, args):
        location = args.get("location", "Unknown")
        return {"temperature": 72, "condition": "sunny", "location": location}

    def produce_args(self):
        return {
            "location": ToolArg(
                name="location",
                arg_type="string",
                description="City name",
                required=True,
                default_value=None,
            ),
        }


def main():
    app = App("weather-bot")

    model = Model.open_ai("gpt-4", Secret.from_env("OPENAI_KEY"))
    agent = Agent(
        name="WeatherBot",
        system_prompt="You help users check the weather.",
        model=model,
        tools=[WeatherTool()],
    )

    app.add_agent(agent)
    app.serve()


if __name__ == "__main__":
    main()

Run shuttl dev and your agent is live.

Core Concepts

Shuttl is built around four composable primitives:

┌─────────────────────────────────────────────────────────────┐
│                         TRIGGERS                            │
│   (API, Rate/Cron, Email, File, Webhook)                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                          AGENT                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   System    │  │    Model    │  │   Tools & Toolkits  │ │
│  │   Prompt    │  │  (GPT, etc) │  │                     │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        OUTCOMES                             │
│   (Streaming, Slack, Webhook, Custom)                       │
└─────────────────────────────────────────────────────────────┘

Agents

The core unit of intelligence. An agent combines a language model with a system prompt and tools to perform tasks.

export const myAgent = new Agent({
    name: "MyAgent",
    systemPrompt: "You are a helpful assistant.",
    model: Model.openAI("gpt-4", Secret.fromEnv("OPENAI_KEY")),
    tools: [],
    triggers: [],
    outcomes: [],
});

Key features:

• Multi-turn conversations with thread management
• Automatic retries with exponential backoff
• Full TypeScript support for type safety

Tools & Toolkits

Give agents the ability to take actions: search databases, call APIs, process data, and more.

const searchTool = {
    name: "search",
    description: "Search the knowledge base",
    schema: Schema.objectValue({
        query: Schema.stringValue("Search query").isRequired(),
        limit: Schema.numberValue("Max results").defaultTo(10),
    }),
    execute: async ({ query, limit }) => {
        return await searchKnowledgeBase(query, limit);
    },
};

Group related tools into Toolkits for clean, modular agent design:

const weatherToolkit = new Toolkit("weather", "Tools for weather information");
weatherToolkit.addTool(getCurrentWeatherTool);
weatherToolkit.addTool(getForecastTool);

Triggers

Define how and when agents are activated:

Trigger	Description	Use Case
ApiTrigger	HTTP endpoint	Chat interfaces, webhooks
Rate	Schedule-based	Cron jobs, periodic tasks
EmailTrigger	Incoming emails	Email automation
FileTrigger	File system changes	Document processing

// Run every hour
triggers: [Rate.hours(1).bindOutcome(new StreamingOutcome())]

// Or use cron for precise scheduling
triggers: [Rate.cron("0 9 * * MON-FRI", "America/New_York")]

Outcomes

Route agent responses to destinations:

Outcome	Description	Use Case
StreamingOutcome	Real-time streaming	Chat interfaces, live feedback
SlackOutcome	Post to Slack	Notifications, reports
CombinationOutcome	Multiple destinations	Broadcast to several channels

outcomes: [
    new CombinationOutcome([
        new StreamingOutcome(),
        new SlackOutcome("#announcements"),
    ]),
]

Models

Language models that power your agents. Currently supports OpenAI with more providers coming soon.

// Complex analysis, important decisions
Model.openAI("gpt-4", Secret.fromEnv("KEY"))

// General purpose, good balance
Model.openAI("gpt-4o", Secret.fromEnv("KEY"))

// High volume, simple tasks
Model.openAI("gpt-4o-mini", Secret.fromEnv("KEY"))

Supported providers:

• ✅ OpenAI (GPT-4, GPT-4o, GPT-4o-mini, GPT-3.5)
• 🚧 Anthropic (Claude 3, Claude 3.5) - Coming Soon
• 🚧 Google (Gemini Pro, Gemini Ultra) - Coming Soon
• 🚧 Local (Ollama, LM Studio) - Coming Soon

Example: Scheduled Reporting Agent

import { Agent, Model, Secret, Rate, SlackOutcome, Schema } from "@shuttl-io/core";

const reportTool = {
    name: "generate_report",
    description: "Generate a daily metrics report",
    schema: Schema.objectValue({
        date: Schema.stringValue("Report date in YYYY-MM-DD format"),
    }),
    execute: async ({ date }) => {
        return { users: 1523, revenue: 42000, churn: 0.02 };
    },
};

export const reportingAgent = new Agent({
    name: "DailyReporter",
    systemPrompt: "Generate concise daily reports. Format as bullet points.",
    model: Model.openAI("gpt-4", Secret.fromEnv("OPENAI_KEY")),
    tools: [reportTool],
    triggers: [
        Rate.cron("0 9 * * *", "America/New_York")  // 9 AM EST daily
    ],
    outcomes: [
        new SlackOutcome("#metrics-channel")
    ],
});

CLI Commands

Install the Shuttl CLI:

curl -fsSL https://shuttl.dev/install.sh | bash

Command	Description
shuttl dev	Interactive development with TUI
shuttl serve	Expose agents as HTTP endpoints
shuttl build	Build your agent for deployment

Configuration

Create shuttl.json in your project root:

{
    "app": "node --require ts-node/register ./src/main.ts"
}

Secrets Management

Never hardcode API keys. Use the Secret class:

// Good
model: Model.openAI("gpt-4", Secret.fromEnv("OPENAI_KEY"))

// Bad - never do this
model: Model.openAI("gpt-4", "sk-abc123...")

What Can You Build?

• Customer Support Bots - Agents that understand context, access your knowledge base, and escalate when needed
• Automated Workflows - Schedule agents to process data, generate reports, or sync systems
• Internal Tools - AI-powered assistants that integrate with your existing stack
• Content Pipelines - Agents that create, review, and publish content

License

MIT

Links

• Documentation
• GitHub
• Website