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.