Implementation Plan

1. Code Structure

New Files to Create

• packages/agent/src/tools/interaction/agentStart.ts
• packages/agent/src/tools/interaction/agentMessage.ts
• packages/agent/src/tools/interaction/agentStart.test.ts
• packages/agent/src/tools/interaction/agentMessage.test.ts

Shared State

Create a shared state module to track running agents:

• packages/agent/src/tools/interaction/agentState.ts - Will contain a Map similar to processStates in shellStart

2. Implementation Details

agentState.ts

import { CoreMessage } from 'ai';
import { v4 as uuidv4 } from 'uuid';
import { Tool } from '../../core/types.js';
import { ToolContext } from '../../core/toolAgent/types.js';

// Define AgentState type
export type AgentState = {
  instanceId: string;
  goal: string;
  prompt: string;
  tools: Tool[];
  context: ToolContext;
  messages: CoreMessage[];
  status: 'running' | 'paused' | 'completed' | 'error';
  result: string;
  error?: string;
  lastUpdated: number;
};

// Global map to store agent states
export const agentStates: Map<string, AgentState> = new Map();

// Helper to create a new agent instance ID
export const createAgentInstanceId = (): string => {
  return uuidv4();
};

agentStart.ts

import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';
import { Tool, ToolContext } from '../../core/types.js';
import { getTools } from '../getTools.js';
import { agentStates, createAgentInstanceId, AgentState } from './agentState.js';
import { getDefaultSystemPrompt, getModel } from '../../core/toolAgent/index.js';

// Similar schema to current subAgent but returns immediately
const parameterSchema = z.object({
  description: z
    .string()
    .describe("A brief description of the sub-agent's purpose (max 80 chars)"),
  goal: z
    .string()
    .describe('The main objective that the sub-agent needs to achieve'),
  projectContext: z
    .string()
    .describe('Context about the problem or environment'),
  workingDirectory: z
    .string()
    .optional()
    .describe('The directory where the sub-agent should operate'),
  relevantFilesDirectories: z
    .string()
    .optional()
    .describe('A list of files, which may include ** or * wildcard characters'),
});

const returnSchema = z.object({
  instanceId: z.string().describe('The ID of the created agent instance'),
  status: z.string().describe('The current status of the agent'),
});

// Implementation will start the agent asynchronously and return immediately

agentMessage.ts

import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';
import { Tool } from '../../core/types.js';
import { agentStates } from './agentState.js';

const parameterSchema = z.object({
  instanceId: z.string().describe('The ID returned by agentStart'),
  instruction: z
    .string()
    .optional()
    .describe('Optional instruction or guidance to send to the agent'),
  action: z
    .enum(['get_status', 'pause', 'resume', 'terminate'])
    .optional()
    .describe('Action to perform on the agent'),
  description: z
    .string()
    .describe('The reason for this agent interaction (max 80 chars)'),
});

const returnSchema = z.object({
  status: z.string().describe('The current status of the agent'),
  result: z.string().describe('The current result or output from the agent'),
  error: z.string().optional().describe('Error message if any'),
});

// Implementation will handle bidirectional communication with the agent

3. Execution Flow

1. Agent Start Process:

   • Create a new agent instance ID
   • Initialize agent state in the global map
   • Start agent execution in a separate async process
   • Return the instance ID immediately

2. Agent Message Process:

   • Get the agent state from the global map
   • If sending instruction: Add to agent's message queue
   • If requesting status: Return current state
   • If terminating: Clean up resources

3. Background Agent Execution:

   • Run in an async manner without blocking
   • Update agent state as execution progresses
   • Handle completion and cleanup

4. Testing Strategy

1. Unit Tests:

   • Test agentStart and agentMessage independently
   • Mock the toolAgent execution for faster tests

2. Integration Tests:

   • Test the full flow with actual agent execution
   • Test parallel execution of multiple agents
   • Test termination and cleanup

5. Documentation Updates

1. Tool Documentation:

   • Add detailed documentation for both tools
   • Provide examples of common usage patterns

2. Migration Guide:

   • Explain differences between subAgent and agentStart/agentMessage
   • Provide guidance on when to use each approach

6. Timeline Estimate

• Research and Design: 1 day
• Implementation: 2-3 days
• Testing: 1-2 days
• Documentation: 1 day
• Code Review and Fixes: 1-2 days

Total: 1-2 weeks depending on complexity and integration challenges

/mycoder, can you implement this as a PR?

I've implemented the agentStart and agentMessage tools as requested in this issue. The implementation follows the pattern of shellStart and shellMessage tools and maintains backward compatibility with the existing subAgent tool.

The PR is available here: #205

Key features implemented:

• agentStart: Starts a sub-agent and returns an instance ID immediately
• agentMessage: Allows interaction with a running sub-agent, including monitoring progress, providing guidance, and termination
• Documentation explaining both approaches and how to use them
• Tests for the new tools

The implementation allows for:

• Running multiple sub-agents in parallel
• Monitoring sub-agent progress
• Providing guidance to sub-agents
• Terminating sub-agents if needed

I've implemented the agentStart and agentMessage tools as requested in this issue. The implementation follows the pattern of shellStart and shellMessage tools and maintains backward compatibility with the existing subAgent tool.

The PR is available here: #205

Key features implemented:

• agentStart: Starts a sub-agent and returns an instance ID immediately
• agentMessage: Allows interaction with a running sub-agent, including monitoring progress, providing guidance, and termination
• Documentation explaining both approaches and how to use them
• Tests for the new tools

The implementation allows for:

• Running multiple sub-agents in parallel
• Monitoring sub-agent progress
• Providing guidance to sub-agents (limited implementation in current version)
• Terminating sub-agents if needed

Let me know if you'd like any changes or have any questions about the implementation!

🎉 This issue has been resolved in version mycoder-agent-v1.1.0 🎉

The release is available on:

• pnpm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀