Skip to main content

SDK Guide

The SmythOS SDK lets you define, configure, and extend agents in TypeScript.
It sits on top of the SmythOS Runtime Environment, giving you a clean API to build workflows, add skills, and connect components programmatically.

When to use the SDK

Use the SDK when you need:

  • Version-controlled agent projects
  • Advanced logic or backend integrations
  • Automated testing or CI/CD pipelines
  • Reusable workflows as part of a larger codebase

Key SDK Capabilities​

FeatureWhat you can do with it
Agent APIDefine, configure, and manage agents in TypeScript
SkillsAdd custom functions and API calls
ComponentsCompose modular workflows (LLMs, APIs, logic, data)
StreamingStream agent output for real-time applications
Storage/VectorDBUse built-in connectors for memory and state
State HandlingSave and reload agent state or skills

Getting Started​

Install the SDK:

npm install @smythos/sdk

Create your first agent​

import { Agent } from '@smythos/sdk';

const agent = new Agent({
    name: 'Assistant',
    model: 'gpt-4o',
    behavior: 'You answer user questions.',
});

Add a skill​

agent.addSkill({
    name: 'echo',
    description: 'Repeat the user input.',
    process: async ({ text }) => text,
});

Prompt the agent​

const result = await agent.prompt('Tell me about SmythOS.');
console.log(result);
Tip

Skills can be private (for internal use) or exposed to the LLM (ai_exposed: true) to be chosen automatically in workflows.

Core Building Blocks​

Agents​

An agent defines a model, behavior, and skills.

const agent = new Agent({
    name: 'DataBot',
    model: 'gpt-4',
    behavior: 'Summarizes and analyzes data.',
});

Skills​

Extend agent behavior with custom skills.

agent.addSkill({
    name: 'summarize',
    description: 'Summarizes text.',
    ai_exposed: true,
    process: async ({ input }) => summarizeText(input),
});

const sum = await agent.call('summarize', { input: 'SmythOS is an agent runtime.' });

Components​

Combine modular building blocks like LLMs, classifiers, or API connectors.

import { GenAILLM, Classifier } from '@smythos/sdk';

const llm = GenAILLM({ model: 'gpt-4o' }, agent);
const classifier = Classifier({ classes: ['news', 'sports'] }, agent);

classifier.in({ Input: llm.out.Reply });

Prompting and Streaming​

Prompt normally:

const output = await agent.prompt('How does vector search work?');

Stream responses in real time:

const stream = await agent.prompt('Stream me this.').stream();
stream.on('data', (chunk) => process.stdout.write(chunk));
When to use streaming

Use streaming for chat UIs, live dashboards, or any case where partial output should appear immediately.

Integration Patterns​

You can integrate SDK agents into larger systems:

  • Save or load agent state for persistence
  • Use connectors for LLMs, storage, or vector databases
  • Run locally for dev; customize configs for production
  • Pair with Enterprise Deployment for scaling

Examples and Next Steps​

Explore more in the SDK examples folder.

Combine with Studio

You can import SDK-built agents into Agent Studio for visualization, testing, and collaboration.