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.

## Why Use Sub-Agents

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.

## Setup

Install Astreus in your project:

```bash
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.

## Creating Specialist Agents

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

```typescript
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:

```typescript
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.

## Building the Coordinator

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

```typescript
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.

## Task Delegation

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

```typescript
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.

## How It Works

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.

## Complete Example

Here's a full working example:

```typescript
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);
```

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

## Agent Creation Parameters

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.

## Delegation Options

The `.ask()` method supports multiple delegation strategies:

```typescript
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.

## Common Patterns

Sequential pipeline for dependent tasks:

```typescript
// 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.

## When to Use Sub-Agents

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.

## Getting Started

Clone the complete example repository:

```bash
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.

## Next Steps

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.