Communication & Event Types

This page describes types related to agent communication, execution control, and event handling within Agent Forge.

Message Interface

Represents a single message within an agent's conversation history. This structure is used for interacting with LLMs.

export interface Message {
  role: "system" | "user" | "assistant" | "tool"; // The role of the message sender.
  content: string;                              // The textual content of the message.
  name?: string;                                 // Optional: Name of the user or tool, if applicable.

  // For assistant messages that include requests to call tools:
  tool_calls?: Array<{
    id: string;        // A unique ID for the tool call.
    type: "function";   // Type of the tool call, typically "function".
    function: {
      name: string;      // Name of the function/tool to call.
      arguments: string; // JSON string of arguments for the function.
    };
  }>;

  // For messages that are results of a tool call:
  tool_call_id?: string; // The ID of the tool call this message is a response to.
}

This interface is similar to ChatCompletionMessageParam from token.js but is specific to Agent Forge's internal representation.

ExecutionMode Enum

Defines the different modes in which agents or groups of agents can be executed.

export enum ExecutionMode {
  SEQUENTIAL = "sequential", // Agents run one after another, like in a Workflow.
  HIERARCHICAL = "hierarchical", // Agents collaborate under a manager, like in a Team.
}

Used by AgentForge.runWithMode() and influences how managerOrFirstAgentName and memberAgentNames parameters are interpreted.

AgentForgeEvents Enum

Lists the various event types that are emitted by the framework, particularly via the globalEventEmitter or an LLM instance's event emitter. These can be used with EventEmitter.on() to subscribe to framework activities.

export enum AgentForgeEvents {
  // Emitted when an agent sends a message, often in a team or workflow context.
  AGENT_COMMUNICATION = "agent:communication",
  
  // Emitted when a step in a Workflow completes.
  WORKFLOW_STEP_COMPLETE = "workflow:step_complete",
  
  // Emitted when a task assigned by a Team manager to a member agent is completed.
  TEAM_TASK_COMPLETE = "team:task_complete",
  
  // Emitted when an overall execution (agent run, workflow run, team run) finishes.
  EXECUTION_COMPLETE = "execution:complete",
  
  // Emitted for each chunk of data when an LLM response is being streamed.
  LLM_STREAM_CHUNK = "llm:stream_chunk",
  
  // Emitted when an LLM streaming response has fully completed.
  LLM_STREAM_COMPLETE = "llm:stream_complete",
}

See enableConsoleStreaming() for an example of how these events are used for logging. Associated event data structures (e.g., AgentCommunicationEvent, LLMStreamEvent) provide the payload for these events.

AgentCommunicationEvent Interface

This interface defines the payload for the AgentForgeEvents.AGENT_COMMUNICATION event.

export interface AgentCommunicationEvent {
  sender: string;        // The name of the agent or entity sending the message.
  recipient?: string;     // Optional: The name of the intended recipient agent.
  message: string;       // The content of the communication.
  timestamp: number;     // Unix timestamp (milliseconds) of when the event occurred.
}

LLMStreamEvent Interface

This interface defines the payload for the AgentForgeEvents.LLM_STREAM_CHUNK event. It's also relevant for understanding the data provided up to the point of an AgentForgeEvents.LLM_STREAM_COMPLETE event.

export interface LLMStreamEvent {
  agentName: string;     // The name of the agent whose LLM call is streaming.
  chunk: string;         // The piece of text received from the LLM stream.
                         // For `LLM_STREAM_CHUNK`, this is the delta. 
                         // For `LLM_STREAM_COMPLETE`, this might represent the full response if aggregated.
  isDelta: boolean;      // True if the chunk is a delta, false if it's a complete segment (less common for raw chunks).
  isComplete: boolean;   // True if this event signifies the end of the stream (used by `LLM_STREAM_COMPLETE`).
}

StreamingOptions Interface

Defines options for operations that support streaming output, potentially offering a direct callback for chunks.

export interface StreamingOptions {
  stream: boolean;                      // Whether to enable streaming for the operation.
  onChunk?: (chunk: string) => void;    // Optional callback function to be invoked with each string chunk of data 
                                        // as it is streamed. This is often used in conjunction with events like 
                                        // `AgentForgeEvents.LLM_STREAM_CHUNK` but can provide a more direct way
                                        // to process streamed text.
}

This interface can be used by higher-level functions or utilities within Agent Forge that wrap streaming operations. If an onChunk handler is provided, it typically receives the same string data as the chunk property of an LLMStreamEvent.