Building Advanced Sub-Agents in Astreus

Advanced multi-agent systems enable sophisticated workflows where specialized agents coordinate to solve complex problems. This guide explores building production-ready agent teams using the Astreus framework with real-world patterns for delegation, coordination, and orchestration.

Before building advanced sub-agent systems, configure your environment with the necessary API keys and database connection.

BashCopy
# .env file
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
DB_URL=sqlite://./astreus.db

The database URL enables memory and knowledge base features. SQLite works well for development, while PostgreSQL is recommended for production deployments.

Different AI models excel at different tasks. GPT-4o provides strong analytical reasoning, while Claude 3.5 Sonnet produces more natural, creative content. Advanced systems combine multiple models strategically based on task requirements.

The coordinator pattern works best for multi-model systems. A coordinator agent analyzes requests and delegates subtasks to specialist agents, each using the model that best fits their role.

The strategic planner handles high-level analytical reasoning and planning tasks. Memory and knowledge base integration enable contextual decision-making.

TypeScriptCopy
const strategicPlanner = await Agent.create({
  name: 'StrategicPlanner',
  model: 'gpt-4o',
  systemPrompt: 'You are a strategic planner. Analyze complex problems and develop comprehensive plans.',
  memory: true,
  knowledge: true
});

The Agent.create() method instantiates agents with full configuration support. Memory enables learning from past interactions, while knowledge bases provide access to curated information.

Claude excels at creative writing and narrative generation. Vision capabilities allow processing images alongside text for richer content creation.

TypeScriptCopy
const creativeWriter = await Agent.create({
  name: 'CreativeWriter',
  model: 'claude-3-5-sonnet-20241022',
  systemPrompt: 'You are a creative writer. Generate engaging, natural prose that connects with readers.',
  vision: true
});

Vision support means the writer can analyze images, screenshots, or diagrams and incorporate visual context into written content.

The data scientist agent combines analytical capabilities with tool integration for statistical analysis and data processing. Tools are registered using registerPlugin() after agent creation.

TypeScriptCopy
const dataScientist = await Agent.create({
  name: 'DataScientist',
  model: 'gpt-4o',
  systemPrompt: 'You are a data scientist. Perform statistical analysis and extract insights from data.'
});

// Register tools via plugin system
await dataScientist.registerPlugin({
  name: 'analytics',
  version: '1.0.0',
  description: 'Data analysis tools',
  tools: [
    {
      name: 'analyzeDataset',
      description: 'Perform statistical analysis on datasets',
      parameters: {
        dataset: { name: 'dataset', type: 'string', description: 'Dataset name or path', required: true },
        metrics: { name: 'metrics', type: 'array', description: 'Metrics to calculate' }
      },
      handler: async (params) => {
        // Implementation here
        return { success: true, data: { /* analysis results */ } };
      }
    }
  ]
});
more

Tools extend agent capabilities beyond text generation. The data scientist can call custom functions for specialized operations like statistical calculations or database queries. Tools are registered via the plugin system using registerPlugin(), which provides a clean separation between agent configuration and tool definitions.

The coordinator orchestrates specialist agents to handle complex, multi-faceted requests. It accepts sub-agents through the subAgents parameter.

TypeScriptCopy
const executiveCoordinator = await Agent.create({
  name: 'ExecutiveCoordinator',
  model: 'gpt-4o',
  systemPrompt: `You coordinate a team of specialist agents:
  - StrategicPlanner: for analytical reasoning and planning
  - CreativeWriter: for content creation and narrative
  - DataScientist: for data analysis and insights
  
  Analyze requests, delegate to appropriate specialists, and synthesize results.`,
  subAgents: [strategicPlanner, creativeWriter, dataScientist]
});
more

By passing agents to the subAgents array, the coordinator gains the ability to delegate tasks. The framework handles routing and execution automatically.

The coordinator uses different delegation strategies depending on the task. Sequential execution processes subtasks in order, while parallel delegation handles independent work simultaneously.

TypeScriptCopy
const result = await executiveCoordinator.ask(
  'Analyze market trends and create an executive summary',
  {
    useSubAgents: true,
    delegation: 'auto',
    coordination: 'sequential'
  }
);

The delegation: 'auto' setting lets the coordinator decide which specialists to involve. Sequential coordination ensures subtasks complete in order, which matters when later tasks depend on earlier results.

When subtasks are independent, parallel coordination reduces total execution time significantly.

TypeScriptCopy
const parallelResult = await executiveCoordinator.ask(
  'Research competitors A, B, and C',
  {
    useSubAgents: true,
    delegation: 'auto',
    coordination: 'parallel'
  }
);

The coordinator dispatches multiple specialists simultaneously. Each researches a different competitor, and the coordinator waits for all results before synthesizing the final response.

Memory allows agents to learn from conversations and recall important context. The extractionLevel parameter controls how aggressively the agent extracts facts.

TypeScriptCopy
const accountManager = await Agent.create({
  name: 'AccountManager',
  model: 'gpt-4o',
  systemPrompt: 'You manage client relationships. Remember preferences, history, and needs.',
  memory: true
});

Moderate extraction balances coverage with precision. The agent remembers key facts without overwhelming storage with trivial details. Settings range from 'minimal' to 'aggressive'.

Knowledge bases provide agents with curated information. Unlike memory, which comes from conversations, knowledge bases contain documents you explicitly add.

TypeScriptCopy
const supportAgent = await Agent.create({
  name: 'SupportAgent',
  model: 'gpt-4o',
  systemPrompt: 'You help customers with product questions. Search the knowledge base for accurate information.',
  knowledge: true
});

The agent searches the knowledge base semantically when answering questions. This grounds responses in authoritative sources rather than relying solely on training data.

Production systems need resilience. Configure retry logic and fallback models for when primary models fail.

TypeScriptCopy
const resilientAgent = await Agent.create({
  name: 'ResilientAgent',
  model: 'gpt-4o',
  systemPrompt: 'You handle customer requests reliably.',
  debug: true
});

If the primary model fails after retries, the agent automatically switches to the fallback. Exponential backoff prevents overwhelming rate limits during temporary outages.

Model costs vary dramatically. Strategic selection can reduce costs by 50-70% without sacrificing quality where it matters.

TypeScriptCopy
// Premium model for complex analysis
const analyst = await Agent.create({
  name: 'Analyst',
  model: 'gpt-4o',
  systemPrompt: 'You analyze complex business problems.'
});

// Cost-effective model for routine tasks
const formatter = await Agent.create({
  name: 'Formatter',
  model: 'gpt-4o-mini',
  systemPrompt: 'You format data into structured outputs.'
});
more

GPT-4o-mini costs a fraction of GPT-4o per token. Use it for tasks like formatting, validation, or basic transformations where advanced reasoning isn't required.

Use a fast, cheap model to filter requests before engaging expensive models. This pattern dramatically reduces costs for high-volume systems.

TypeScriptCopy
const triageAgent = await Agent.create({
  name: 'TriageAgent',
  model: 'gpt-4o-mini',
  systemPrompt: `Classify requests as:
  - simple: handle directly
  - complex: escalate to specialist
  - out-of-scope: not something we handle`
});

const coordinator = await Agent.create({
  name: 'Coordinator',
  model: 'gpt-4o',
  systemPrompt: 'Handle escalated complex requests.',
  subAgents: [triageAgent]
});
more

The coordinator asks the triage agent to assess each request first. Simple requests never hit the expensive model, significantly reducing overall costs.

For high-stakes decisions, have multiple agents independently analyze the question. Make decisions based on agreement levels.

TypeScriptCopy
const riskAnalyst1 = await Agent.create({
  name: 'RiskAnalyst1',
  model: 'gpt-4o',
  systemPrompt: 'You assess financial risk conservatively.'
});

const riskAnalyst2 = await Agent.create({
  name: 'RiskAnalyst2',
  model: 'claude-3-5-sonnet-20241022',
  systemPrompt: 'You assess financial risk conservatively.'
});

const decisionMaker = await Agent.create({
  name: 'DecisionMaker',
  model: 'gpt-4o',
  systemPrompt: 'Review risk assessments and make decisions. If analysts disagree, flag for human review.',
  subAgents: [riskAnalyst1, riskAnalyst2]
});
more

Using different models for each analyst reduces the risk of shared biases. Disagreement between analysts signals that the decision needs human judgment.

For detailed token tracking, use the task-based API which provides usage statistics.

TypeScriptCopy
const task = await executiveCoordinator.createTask({
  prompt: 'Generate quarterly market analysis',
  useSubAgents: true
});

const result = await executiveCoordinator.executeTask(task.id);

console.log(`Response: ${result.response}`);
console.log(`Total tokens: ${result.usage?.totalTokens}`);

The task-based API returns detailed execution information including token usage. Use this data to optimize prompts and understand costs.

Clear system prompts define agent behavior precisely. Specify role, responsibilities, and boundaries.

TypeScriptCopy
const contractAnalyzer = await Agent.create({
  name: 'ContractAnalyzer',
  model: 'gpt-4o',
  systemPrompt: `You analyze legal contracts for business clients.
  
  Responsibilities:
  - Identify key terms, obligations, and deadlines
  - Flag unusual or risky clauses
  - Summarize in plain English
  
  Boundaries:
  - Never provide legal advice, only analysis
  - Cite specific sections when flagging issues
  - Acknowledge limitations of automated review`
});
more

Explicit boundaries prevent agents from overstepping their expertise. The contract analyzer won't attempt legal advice, keeping outputs within appropriate scope.

Here's a complete multi-agent system for generating research reports with parallel processing and quality assurance.

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

// Data collection agent
const dataCollector = await Agent.create({
  name: 'DataCollector',
  model: 'gpt-4o',
  systemPrompt: 'You gather and analyze market data.'
});

// Competitive intelligence agent
const competitiveIntel = await Agent.create({
  name: 'CompetitiveIntel',
  model: 'gpt-4o',
  systemPrompt: 'You analyze competitors and market positioning.'
});

// Report writer using Claude
const reportWriter = await Agent.create({
  name: 'ReportWriter',
  model: 'claude-3-5-sonnet-20241022',
  systemPrompt: 'You write executive reports. Create clear, compelling narratives.'
});

// Quality assurance with cost-effective model
const qualityChecker = await Agent.create({
  name: 'QualityChecker',
  model: 'gpt-4o-mini',
  systemPrompt: 'You check reports for errors and clarity issues.'
});

// Research coordinator
const researchCoordinator = await Agent.create({
  name: 'ResearchCoordinator',
  model: 'gpt-4o',
  systemPrompt: `You coordinate research projects.
  
  Workflow:
  1. DataCollector and CompetitiveIntel work in parallel
  2. ReportWriter synthesizes their findings
  3. QualityChecker reviews final output
  4. Return polished report`,
  subAgents: [dataCollector, competitiveIntel, reportWriter, qualityChecker]
});

// Execute the pipeline
const report = await researchCoordinator.ask(
  'Generate market research for electric vehicles in North America',
  {
    useSubAgents: true,
    coordination: 'sequential'
  }
);

console.log(report);
more

This system combines GPT-4o's analytical capabilities for data and competitive analysis, Claude's writing strength for report generation, and a cost-effective model for QA. The coordinator handles the entire workflow automatically.

You can run the official examples by cloning the repository or installing the package independently.

BashCopy
# Clone and run examples
git clone https://github.com/astreus-ai/sub-agents-advanced
cd sub-agents-advanced
npm install
npm run dev

# Or install package for your own project
npm install @astreus-ai/astreus

The repository contains complete working examples demonstrating all patterns discussed in this guide.

Test individual agents first, then test coordination logic with integration tests.

TypeScriptCopy
// Test individual agent
const writerResult = await creativeWriter.ask(
  'Write a product description for wireless headphones'
);

assert(writerResult.length > 100);
assert(writerResult.includes('wireless'));

// Test coordination
const coordinatedResult = await executiveCoordinator.ask(
  'Create a marketing campaign for wireless headphones',
  { useSubAgents: true }
);

assert(coordinatedResult.length > 0);
assert(coordinatedResult.includes('target audience'));
more

Integration tests verify that agents collaborate correctly and the coordinator routes tasks to appropriate specialists.

Add comprehensive logging and monitoring for production deployments.

TypeScriptCopy
const productionAgent = await Agent.create({
  name: 'ProductionAgent',
  model: 'gpt-4o',
  systemPrompt: 'You handle customer requests.',
  debug: true
});

Comprehensive instrumentation enables debugging issues, understanding usage patterns, and optimizing performance based on real-world behavior.

Advanced sub-agent systems leverage multiple models strategically through coordination patterns. Use Agent.create() to instantiate agents with full configuration support including memory, knowledge bases, and tools.

Implement delegation with the useSubAgents option and coordination strategies like sequential or parallel execution. Monitor token usage and costs to optimize model selection.

Add memory for agents that need conversation context. Integrate knowledge bases for grounding in authoritative sources. Implement error handling with retries and fallback models for production resilience.

Start with clear system prompts that define roles and boundaries. Test agents individually and as coordinated systems. Use instrumentation to learn from real usage and continuously improve your multi-agent architecture.

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