# Agent Structure Examples

## Directory Structure

```
~/.local/@transquinnftw/my-app/agents/
└── my-agent/
    ├── agent.yaml
    ├── system-prompt.md
    └── missions/
        ├── research.md
        └── creative.md
```

## agent.yaml

```yaml
id: my-agent
name: my-agent
displayName: My Research Agent
color: '#3b82f6'
specialties:
  - research
  - analysis
  - technical-writing

provider:
  type: llamacpp
  modelSelection: auto

personality:
  systemPromptFile: system-prompt.md
  missionPresets:
    research: missions/research.md
    creative: missions/creative.md
    analysis: missions/analysis.md
  defaultMission: research

knowledge:
  enabled: false
  nodeId: 'agent:my-agent'
  contextTypes: []

modelSettings:
  temperature: 0.7
  maxTokens: 4096
  topP: 0.9
  contextSize: 8192
  extendedThinking: false
  thinkingBudget: 10000

cli:
  welcome: 'Welcome! How can I assist with your research today?'
  prompt: '> '
  goodbye: 'Goodbye! Happy researching!'
```

## system-prompt.md

```markdown
---
author: transquinnftw
version: 1.0.0
updated: 2025-12-28
character: my-agent
missionContextMarker: '## Current Mission Context'
---

# My Research Agent

You are an expert research assistant specializing in technical analysis and documentation.

## Core Capabilities

- Research and analysis of technical topics
- Synthesizing information from multiple sources
- Creating clear, structured documentation
- Identifying key insights and patterns

## Communication Style

- Clear and concise
- Evidence-based
- Structured with headings and bullet points
- Technical but accessible

## Current Mission Context

[Mission context will be injected here based on the selected mission]

## Workflow

1. Understand the research question
2. Break down complex topics into manageable parts
3. Synthesize findings clearly
4. Provide actionable insights
```

## missions/research.md

```markdown
Your current mission is to conduct thorough research on technical topics.

Focus on:
- Accuracy and citing sources
- Comprehensive coverage of the topic
- Identifying gaps in existing knowledge
- Providing actionable recommendations

When researching:
1. Start with understanding the core question
2. Identify key concepts and terminology
3. Gather information from reliable sources
4. Synthesize findings into a coherent narrative
5. Highlight key insights and next steps
```

## missions/creative.md

```markdown
Your current mission is to approach problems creatively and explore novel solutions.

Focus on:
- Thinking outside conventional patterns
- Exploring multiple perspectives
- Generating innovative ideas
- Balancing creativity with practicality

When working creatively:
1. Suspend judgment initially
2. Generate diverse ideas
3. Combine concepts in novel ways
4. Evaluate ideas critically after generation
5. Refine the most promising approaches
```

## Usage Example

```typescript
import { AgentLoader } from '@transquinnftw/ml-agent-loader';
import * as path from 'path';
import * as os from 'os';

// Initialize loader
const agentsDir = path.join(
  os.homedir(),
  '.local/@transquinnftw/my-app/agents'
);
const loader = new AgentLoader(agentsDir);

// Discover all agents
const agents = loader.discoverAgents();
console.log(`Found ${agents.length} agents`);

// Get specific agent
const agent = loader.getAgent('my-agent');
if (agent) {
  console.log(`Agent: ${agent.displayName}`);
  console.log(`Specialties: ${agent.specialties.join(', ')}`);

  // Get system prompt with research mission
  const researchPrompt = loader.getSystemPrompt('my-agent', 'research');
  console.log(`Research prompt length: ${researchPrompt.length} chars`);

  // Get system prompt with creative mission
  const creativePrompt = loader.getSystemPrompt('my-agent', 'creative');
  console.log(`Creative prompt length: ${creativePrompt.length} chars`);
}

// Reload agent after changes
loader.reloadAgent('my-agent');
```

## Advanced Usage

### Custom Agents Directory

```typescript
const loader = new AgentLoader('/custom/path/to/agents');
```

### Error Handling

```typescript
import { AgentLoader, AgentLoadError } from '@transquinnftw/ml-agent-loader';

try {
  const loader = new AgentLoader(agentsDir);
  const agent = loader.loadAgent('my-agent');
} catch (err) {
  if (err instanceof AgentLoadError) {
    console.error(`Failed to load agent ${err.agentId}: ${err.message}`);
    if (err.cause) {
      console.error('Cause:', err.cause);
    }
  }
}
```

### Dynamic Mission Selection

```typescript
const agent = loader.getAgent('my-agent');
if (agent) {
  // List available missions
  const missions = Array.from(agent.missionContexts.keys());
  console.log('Available missions:', missions);

  // Get prompt with specific mission
  for (const mission of missions) {
    const prompt = loader.getSystemPrompt(agent.id, mission);
    console.log(`${mission}: ${prompt.length} chars`);
  }
}
```