Build an AI Agent

This tutorial walks you through building an AI agent with Minions, starting simple and growing in complexity.

Step 1: A Flat Agent

The simplest possible agent is a single minion:

TypeScript

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

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

const { minion: agent } = createMinion({
  title: 'Research Assistant',
  fields: {
    role: 'researcher',
    model: 'gpt-4',
    systemPrompt: 'You are a research assistant that finds and summarizes papers.',
    temperature: 0.3,
    tools: ['web-search', 'summarize'],
  },
}, agentType);

Python

from minions import TypeRegistry, create_minion

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

agent, _ = create_minion(
    {
        "title": "Research Assistant",
        "fields": {
            "role": "researcher",
            "model": "gpt-4",
            "systemPrompt": "You are a research assistant that finds and summarizes papers.",
            "temperature": 0.3,
            "tools": ["web-search", "summarize"],
        },
    },
    agent_type,
)

That’s it. A complete, validated agent definition.

Step 2: Add Memory

Agents need to remember things. Create a thought minion and link it:

TypeScript

const thoughtType = registry.getBySlug('thought')!;

const { minion: styleGuide } = createMinion({
  title: 'Research Style Guide',
  fields: {
    content: 'Always cite sources. Prefer peer-reviewed papers. Summarize in 3 paragraphs.',
    confidence: 0.95,
    source: 'internal-guidelines',
  },
}, thoughtType);

Python

thought_type = registry.get_by_slug("thought")

style_guide, _ = create_minion(
    {
        "title": "Research Style Guide",
        "fields": {
            "content": "Always cite sources. Prefer peer-reviewed papers. Summarize in 3 paragraphs.",
            "confidence": 0.95,
            "source": "internal-guidelines",
        },
    },
    thought_type,
)

Step 3: Add a Prompt Template

Define how the agent structures its output:

TypeScript

const promptType = registry.getBySlug('prompt-template')!;

const { minion: template } = createMinion({
  title: 'Research Summary Template',
  fields: {
    template: 'Research topic: {{topic}}\n\nSummarize the top {{count}} papers.',
    variables: ['topic', 'count'],
    outputFormat: 'markdown',
  },
}, promptType);

Python

prompt_type = registry.get_by_slug("prompt-template")

template, _ = create_minion(
    {
        "title": "Research Summary Template",
        "fields": {
            "template": "Research topic: {{topic}}\n\nSummarize the top {{count}} papers.",
            "variables": ["topic", "count"],
            "outputFormat": "markdown",
        },
    },
    prompt_type,
)

Step 4: Connect Everything

Use relations to build the tree:

TypeScript

import { RelationGraph } from 'minions-sdk';

const graph = new RelationGraph();

graph.add({ sourceId: agent.id, targetId: styleGuide.id, type: 'parent_of' });
graph.add({ sourceId: agent.id, targetId: template.id, type: 'parent_of' });

const children = graph.getChildren(agent.id);
// => [styleGuide.id, template.id]

Python

from minions import RelationGraph

graph = RelationGraph()

graph.add({"source_id": agent.id, "target_id": style_guide.id, "type": "parent_of"})
graph.add({"source_id": agent.id, "target_id": template.id, "type": "parent_of"})

children = graph.get_children(agent.id)
# => [style_guide.id, template.id]

Step 5: Add Evaluation

Create a test case to verify agent quality:

TypeScript

const testType = registry.getBySlug('test-case')!;

const { minion: test } = createMinion({
  title: 'Research Quality Test',
  fields: {
    input: { topic: 'transformer architectures', count: 3 },
    assertions: { containsCitations: true, minPapers: 3 },
    timeout: 30000,
  },
}, testType);

graph.add({ sourceId: agent.id, targetId: test.id, type: 'parent_of' });

Python

test_type = registry.get_by_slug("test-case")

test, _ = create_minion(
    {
        "title": "Research Quality Test",
        "fields": {
            "input": {"topic": "transformer architectures", "count": 3},
            "assertions": {"containsCitations": True, "minPapers": 3},
            "timeout": 30000,
        },
    },
    test_type,
)

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

Final Structure

Research Assistant (agent)
├── Research Style Guide (thought)        ← memory layer
├── Research Summary Template (prompt)     ← interface layer
└── Research Quality Test (test-case)      ← evaluation layer

Your agent started as a single flat minion and now has memory, templates, and tests — all validated, all queryable, all linked.