The JSII library for Shuttl AI models
npm install @shuttl-io/coreA developer-first framework for building, deploying, and managing AI agents. Stop wrestling with complex infrastructure and start shipping intelligent agents in minutes.
TypeScript/JavaScript:
``bash`
npm install @shuttl-io/coreor
pnpm add @shuttl-io/coreor
yarn add @shuttl-io/core
Python:
`bash`
pip install shuttl-core
Java (Maven):
`xml`
Go:
`bash`
go get github.com/shuttl-io/shuttl-core-go
.NET:
`bash`
dotnet add package shuttl.core
`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],
});
`
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.
`python
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.
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) │
└─────────────────────────────────────────────────────────────┘
The core unit of intelligence. An agent combines a language model with a system prompt and tools to perform tasks.
`typescript`
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
Give agents the ability to take actions: search databases, call APIs, process data, and more.
`typescript`
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:
`typescript`
const weatherToolkit = new Toolkit("weather", "Tools for weather information");
weatherToolkit.addTool(getCurrentWeatherTool);
weatherToolkit.addTool(getForecastTool);
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 |
`typescript
// 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")]
`
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 |
`typescript`
outcomes: [
new CombinationOutcome([
new StreamingOutcome(),
new SlackOutcome("#announcements"),
]),
]
Language models that power your agents. Currently supports OpenAI with more providers coming soon.
`typescript
// 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
`typescript
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")
],
});
`
Install the Shuttl CLI:
`bash`
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 |
Create shuttl.json in your project root:
`json`
{
"app": "node --require ts-node/register ./src/main.ts"
}
Never hardcode API keys. Use the Secret class:
`typescript
// Good
model: Model.openAI("gpt-4", Secret.fromEnv("OPENAI_KEY"))
// Bad - never do this
model: Model.openAI("gpt-4", "sk-abc123...")
``
- 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
MIT