feat: multiagents - components

[pgrayy]

Description

Motivation

The multi-agent module (#547) introduced Node, AgentNode, and basic state primitives. To support the upcoming Graph orchestration pattern (#433), the module needs additional shared components: edges for defining node relationships, a streaming event system for propagating execution progress, an async queue for coordinating parallel node execution, and richer state types for tracking execution lifecycle and results.

This PR adds these foundational components incrementally, keeping them decoupled from the Graph implementation itself so they can be reviewed and landed independently.

Resolves: #433 (partial)

Public API Changes

New exports from @strands-agents/sdk/multiagent:

// State types for tracking execution lifecycle
import {
  Status,              // PENDING | EXECUTING | COMPLETED | FAILED | CANCELLED
  NodeState,           // Per-node execution state
  NodeResult,          // Result of a single node execution
  MultiAgentResult,    // Aggregate result from a multi-agent execution
  MultiAgentState,     // Shared state with per-node tracking
} from '@strands-agents/sdk/multiagent'

// Edge definitions for node relationships
import { Edge, EdgeDefinition, EdgeHandler } from '@strands-agents/sdk/multiagent'

// Streaming events for execution progress
import {
  NodeStreamUpdateEvent,     // Wraps inner streaming events from a node
  NodeResultEvent,           // Emitted when a node finishes
  MultiAgentHandoffEvent,    // Emitted on node-to-node transitions
  MultiAgentResultEvent,     // Final event with aggregate result
} from '@strands-agents/sdk/multiagent'

• NodeType moved from types.ts into nodes.ts (same public export, types.ts removed).
• Queue is an internal component right now.

Type of Change

New feature

Testing

How have you tested the change?

I ran npm run check

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Comment

This PR adds well-designed foundational components for multi-agent orchestration. The API design aligns well with the Python SDK patterns and follows repository conventions.

Review Categories

• Testing: New files (edge.ts) and classes (NodeState, MultiAgentResult, MultiAgentState) need unit test coverage to maintain the 80%+ coverage requirement
• API Review: This PR introduces significant new public APIs. Consider adding the needs-api-review label per API Bar Raising guidelines, particularly for the new state types and event classes that customers will directly use
• Documentation: Minor TSDoc inconsistency in Node.config description

The overall architecture and code quality look solid. The incremental approach to building these components is appreciated.

[pgrayy]

#433