Building Basic Sub-Agents in Astreus

Sub-agents in Astreus allow you to create teams of specialized AI agents that collaborate under a coordinator. Instead of one agent handling everything, each specialist focuses on what it does best.

Single agents struggle with complex tasks requiring different skills. Asking one agent to research and write produces mediocre results. Specialization solves this by letting each agent excel at a specific role.

Install Astreus in your project:

BashCopy
npm install @astreus-ai/astreus

Configure your environment with a .env file:

OPENAI_API_KEY=sk-your-openai-api-key-here
DB_URL=sqlite://./astreus.db

Astreus handles agent management and persistence. You focus on defining agent behaviors and coordination strategies.

Define agents with focused system prompts. Here's a researcher agent:

TypeScriptCopy
import { Agent } from '@astreus-ai/astreus';

const researcher = await Agent.create({
  name: 'Researcher',
  model: 'gpt-4o',
  systemPrompt: 'You are an expert researcher who gathers comprehensive information.'
});

This agent prioritizes accuracy and thoroughness. The focused prompt keeps it specialized.

Now create a writer agent:

TypeScriptCopy
const writer = await Agent.create({
  name: 'Writer',
  model: 'gpt-4o',
  systemPrompt: 'You are a skilled writer who creates clear, engaging content.'
});

The writer transforms information into readable content. Each agent has a distinct, non-overlapping role.

The coordinator orchestrates the team. Create it with sub-agents:

TypeScriptCopy
const mainAgent = await Agent.create({
  name: 'Coordinator',
  model: 'gpt-4o',
  systemPrompt: 'You coordinate tasks between specialized agents.',
  subAgents: [researcher, writer]
});

The coordinator knows its team and how to delegate work. It receives requests, routes them to specialists, and combines results.

Use the .ask() method with sub-agent delegation:

TypeScriptCopy
const result = await mainAgent.ask(
  'Research artificial intelligence trends and write a summary',
  {
    useSubAgents: true,
    delegation: 'auto'
  }
);

console.log(result);

With automatic delegation, the coordinator handles orchestration. It analyzes the request, delegates to the researcher, passes findings to the writer, and returns the final result.

When you call mainAgent.ask() with useSubAgents: true, the coordinator automatically determines which specialists to involve. For the example above, it delegates research to the researcher agent first, then passes those findings to the writer agent.

The delegation: 'auto' option lets the coordinator make smart decisions about task routing. You get the final result without managing individual steps.

Here's a full working example:

TypeScriptCopy
import { Agent } from '@astreus-ai/astreus';

const researcher = await Agent.create({
  name: 'Researcher',
  model: 'gpt-4o',
  systemPrompt: 'You are an expert researcher who gathers comprehensive information.'
});

const writer = await Agent.create({
  name: 'Writer',
  model: 'gpt-4o',
  systemPrompt: 'You are a skilled writer who creates clear, engaging content.'
});

const mainAgent = await Agent.create({
  name: 'Coordinator',
  model: 'gpt-4o',
  systemPrompt: 'You coordinate tasks between specialized agents.',
  subAgents: [researcher, writer]
});

const result = await mainAgent.ask(
  'Research artificial intelligence trends and write a summary',
  {
    useSubAgents: true,
    delegation: 'auto'
  }
);

console.log(result);
more

Run this with npx tsx index.ts or npm run dev if you've set up a package.json script.

The Agent.create() method accepts several key parameters:

• name: Identifies the agent for logging and debugging
• model: The LLM to use (e.g., 'gpt-4o', 'gpt-4-turbo')
• systemPrompt: Defines the agent's behavior and expertise
• subAgents: Array of specialist agents (coordinator only)

Focused system prompts are crucial. They keep agents in their lanes and prevent role confusion.

The .ask() method supports multiple delegation strategies:

TypeScriptCopy
await mainAgent.ask(prompt, {
  useSubAgents: true,  // Enable sub-agent delegation
  delegation: 'auto'   // Automatic task routing
});

Automatic delegation works well for standard workflows. The coordinator decides which agents to involve based on the task.

Sequential pipeline for dependent tasks:

TypeScriptCopy
// Coordinator automatically routes:
// 1. Task to researcher
// 2. Research results to writer
// 3. Final output back to you

This pattern ensures quality at each stage. Each specialist builds on previous work.

Use sub-agents when tasks have distinct phases requiring different expertise. Research and writing naturally map to specialists. Sub-agents excel when quality matters more than speed.

Avoid sub-agents for simple tasks. If one agent with a good prompt works, don't add complexity. Skip sub-agents when speed is critical and coordination overhead isn't worth the quality improvement.

Clone the complete example repository:

BashCopy
git clone https://github.com/astreus-ai/sub-agents-basic
cd sub-agents-basic
npm install

This gives you a working example to experiment with. Modify the system prompts and tasks to understand how coordination works.

Start with a simple two-agent system. Verify coordination works as expected. Then add complexity gradually by introducing additional specialists or more sophisticated delegation logic.

Experiment with different system prompts. The prompt quality directly affects agent performance. Clear, focused prompts produce better results than vague instructions.

Check the Astreus GitHub repository for additional examples and patterns. Hands-on experimentation builds intuition for multi-agent design.

This experiment is written for Astreus v0.5.37. Please ensure you are using a compatible version.