Quick Start

Installation

TypeScript

pnpm add minions-sdk

Python

pip install minions-sdk

Create Your First Agent

TypeScript

import { Minions } from 'minions-sdk';

const minions = new Minions();

const agent = minions.create('agent', {
  title: 'Research Assistant',
  fields: {
    role: 'researcher',
    model: 'gpt-4',
    systemPrompt: 'You are a research assistant.',
    tools: ['web-search', 'summarize'],
  },
});

console.log(agent.data.id);        // generated UUID

Python

from minions import Minions

minions = Minions()

agent = minions.create("agent", {
    "title": "Research Assistant",
    "fields": {
        "role": "researcher",
        "model": "gpt-4",
        "systemPrompt": "You are a research assistant.",
        "tools": ["web-search", "summarize"],
    },
})

print(agent.data.id)         # generated UUID

Link Minions Together

TypeScript

import { Minions } from 'minions-sdk';

const minions = new Minions();

// Create an agent and a skill
const agent = minions.create('agent', { title: 'Agent' });
const skill = minions.create('note', { title: 'Skill' });

// Link them
agent.linkTo(skill.data.id, 'parent_of');

const children = minions.graph.getChildren(agent.data.id);
const tree = minions.graph.getTree(agent.data.id);

Python

from minions import Minions

minions = Minions()

# Create an agent and a skill
agent = minions.create("agent", {"title": "Agent"})
skill = minions.create("note", {"title": "Skill"})

# Link them
agent.link_to(skill.data.id, "parent_of")

children = minions.graph.get_children(agent.data.id)
tree = minions.graph.get_tree(agent.data.id)

Advanced Modular Usage

If you need finer-grained control and tree-shaking, you can bypass the central client and use the underlying standalone functions:

TypeScript

import { TypeRegistry, createMinion, RelationGraph } from 'minions-sdk';

const registry = new TypeRegistry();
const agentType = registry.getBySlug('agent')!;

const { minion: agent } = createMinion({ title: 'Agent' }, agentType);

const graph = new RelationGraph();
graph.add({ sourceId: agent.id, targetId: 'skillId', type: 'parent_of' });

Python

from minions import TypeRegistry, create_minion, RelationGraph

registry = TypeRegistry()
agent_type = registry.get_by_slug("agent")

agent, _ = create_minion({"title": "Agent"}, agent_type)

graph = RelationGraph()
graph.add({"source_id": agent.id, "target_id": "skill_id", "type": "parent_of"})

Validate a Minion File

TypeScript

npx minions-cli validate my-agent.json

Python

# CLI is TypeScript only — use the Python SDK directly
from minions.validation import validate_fields
from minions.schemas import agent_type
import json

with open("my-agent.json") as f:
    data = json.load(f)

result = validate_fields(data.get("fields", {}), agent_type.schema)
print(result.valid)

Next Steps

• Learn about the three core primitives
• Understand the layer model
• Follow the AI agent tutorial