tasq/node_modules/agentic-flow/docs/integrations/CLAUDE_AGENTS_INTEGRATION.md

.claude/agents Integration

This document explains how to use agents from .claude/agents/ directory with the Claude Agent SDK.

Overview

The Claude Agent SDK now supports loading and using agent definitions from your .claude/agents/ directory. This allows you to:

• Reuse existing agents from your Claude Code configuration
• Centralize agent definitions in one location
• Mix and match specialized agents for different tasks
• Leverage agent metadata like descriptions and tools

Quick Start

1. Using a Single Agent

import { getAgent } from './utils/agentLoader.js';
import { claudeAgent } from './agents/claudeAgent.js';

// Load the goal-planner agent
const goalPlanner = getAgent('goal-planner');

// Use it
const result = await claudeAgent(
  goalPlanner,
  'Create a plan to improve our API performance'
);

console.log(result.output);

2. Using Multiple Agents

import { loadAgents } from './utils/agentLoader.js';
import { claudeAgent } from './agents/claudeAgent.js';

// Load all agents
const agents = loadAgents();

// Use different agents for different tasks
const planner = agents.get('goal-planner');
const coder = agents.get('coder');
const reviewer = agents.get('reviewer');

// Execute in sequence
const plan = await claudeAgent(planner, 'Plan feature X');
const code = await claudeAgent(coder, 'Implement ' + plan.output);
const review = await claudeAgent(reviewer, 'Review: ' + code.output);

3. Parallel Execution

const agents = loadAgents();

// Run multiple agents in parallel
const [research, analysis, design] = await Promise.all([
  claudeAgent(agents.get('researcher'), 'Research topic X'),
  claudeAgent(agents.get('code-analyzer'), 'Analyze codebase'),
  claudeAgent(agents.get('system-architect'), 'Design solution')
]);

Agent Definition Format

Agents in .claude/agents/ use markdown files with YAML frontmatter:

---
name: my-agent
description: "What this agent does"
color: purple
tools: Read, Write, Bash
---

You are a specialized agent that...

Your capabilities:
- Capability 1
- Capability 2

[Rest of system prompt]

Required fields:

• name: Unique identifier
• description: Short description of agent's purpose

Optional fields:

• color: Display color in UI
• tools: Comma-separated list of tools

Available Agents

Run this to see all loaded agents:

npm run example:multi-agent

Some Notable Agents

From .claude/agents/:

Planning & Strategy:

• goal-planner - GOAP-based planning and optimization
• planner - Strategic planning and task orchestration

Development:

• coder - Clean code implementation
• reviewer - Code review specialist
• tester - Testing and QA

Flow Nexus:

• flow-nexus-swarm - AI swarm orchestration
• flow-nexus-neural - Neural network training
• flow-nexus-workflow - Workflow automation

GitHub Integration:

• github-modes - GitHub workflow orchestration
• pr-manager - PR management
• code-review-swarm - Automated code reviews

Consensus & Coordination:

• raft-manager - Raft consensus
• byzantine-coordinator - Byzantine fault tolerance
• gossip-coordinator - Gossip protocols

Examples

Example 1: Goal-Planner Agent

npm run example:goal-planner

This demonstrates using the goal-planner agent to create improvement plans.

Example 2: Multi-Agent Orchestration

npm run example:multi-agent

This shows:

• Loading all available agents
• Using multiple agents in sequence
• Agent discovery and listing

API Reference

loadAgents(agentsDir?: string): Map<string, AgentDefinition>

Load all agents from directory.

Parameters:

• agentsDir - Path to agents directory (default: /workspaces/flow-cloud/.claude/agents)

Returns: Map of agent name to AgentDefinition

Example:

const agents = loadAgents();
console.log(`Loaded ${agents.size} agents`);

getAgent(name: string, agentsDir?: string): AgentDefinition | undefined

Get a specific agent by name.

Parameters:

• name - Agent name
• agentsDir - Optional agents directory path

Returns: AgentDefinition or undefined

Example:

const goalPlanner = getAgent('goal-planner');
if (goalPlanner) {
  console.log(goalPlanner.description);
}

listAgents(agentsDir?: string): AgentDefinition[]

Get array of all agents.

Parameters:

• agentsDir - Optional agents directory path

Returns: Array of AgentDefinition

Example:

const allAgents = listAgents();
allAgents.forEach(agent => {
  console.log(`${agent.name}: ${agent.description}`);
});

claudeAgent(agent: AgentDefinition, input: string, onStream?: (chunk: string) => void)

Execute an agent with given input.

Parameters:

• agent - AgentDefinition from loadAgents()
• input - Prompt/task for the agent
• onStream - Optional streaming callback

Returns: { output: string, agent: string }

Example:

const result = await claudeAgent(
  goalPlanner,
  'Create a 3-step plan',
  (chunk) => process.stdout.write(chunk)
);

AgentDefinition Type

interface AgentDefinition {
  name: string;           // Agent identifier
  description: string;    // What the agent does
  systemPrompt: string;   // Full system prompt
  color?: string;         // Optional UI color
  tools?: string[];       // Optional tool list
  filePath: string;       // Source file path
}

Creating Custom Agents

1. Create a markdown file in .claude/agents/:

---
name: my-custom-agent
description: "Specialized agent for my use case"
color: blue
---

You are a specialized agent for...

Your focus areas:
- Area 1
- Area 2

2. Use it in your code:

const myAgent = getAgent('my-custom-agent');
const result = await claudeAgent(myAgent, 'Do something');

Docker Integration

The agent loader works in Docker containers if you mount the .claude/agents directory:

docker run -v /path/to/.claude/agents:/app/.claude/agents \
  claude-agents:latest

Or in docker-compose.yml:

services:
  agents:
    volumes:
      - ../../.claude/agents:/app/.claude/agents:ro

Troubleshooting

Agent Not Found

const agent = getAgent('my-agent');
if (!agent) {
  console.error('Agent not found. Available agents:');
  listAgents().forEach(a => console.log(`  - ${a.name}`));
}

Missing Frontmatter

Agents must have valid frontmatter:

---
name: agent-name
description: "Agent description"
---

Check logs for warnings about missing metadata.

Path Issues in Docker

Ensure the path in agentLoader.ts matches your Docker setup:

const agents = loadAgents('/app/.claude/agents');

Best Practices

1. Use Descriptive Names: Agent names should be clear and specific
2. Keep System Prompts Focused: Each agent should have a clear, single purpose
3. Document Tools: List required tools in frontmatter
4. Version Control: Keep agent definitions in git
5. Test Agents: Validate new agents work before deploying

Advanced: Custom Agent Directory

You can organize agents in subdirectories:

.claude/agents/
  ├── planning/
  │   ├── goal-planner.md
  │   └── strategic-planner.md
  ├── development/
  │   ├── coder.md
  │   └── reviewer.md
  └── operations/
      └── deployment.md

The loader recursively scans all subdirectories.

Performance

• Load Time: ~50ms for 74 agents
• Memory: ~10KB per agent definition
• Caching: Agents loaded once at startup

Next Steps

• Explore existing agents in .claude/agents/
• Create custom agents for your use cases
• Combine agents in workflows
• Add error handling and retry logic
• Implement agent chaining patterns

See Also

• Quick Wins Implementation
• Improvement Plan
• Examples