tl;dr
How do you reliably combine deterministic business logic, parallel retrieval, and noisy LLM calls in production? The Microsoft Agent Framework answers this by modeling workflows as directed graphs: Executors (the nodes) perform the work, and Edges (the connections) define how strongly‑typed messages move between them. That separation makes orchestration explicit, testable, and observable.
Why the graph model matters
Treating a workflow as a directed graph of Executors and Edges gives you:
- Clear separation of responsibilities: what each step does (Executor) versus how messages move between them (Edge).
- Reusability and composition: swap or reuse Executors without changing routing.
- Predictable control flow: keep LLMs as processing nodes, not the controller of your flow.
- Better testability and observability: unit-test Executors, instrument Edges and messages for traceability.
Workflow
- A Workflow is a directed graph (often a DAG) composed of Executors connected by Edges. Workflows are constructed with a WorkflowBuilder API and executed by a runtime.
- The WorkflowBuilder API includes methods like AddEdge/AddFanOutEdge/AddFanInBarrierEdge/AddConditionalEdge and produces an executable workflow object.
Executor (node)
- Definition: the atomic unit of work. Executors receive strongly‑typed messages, perform processing (business logic, API calls, or invoking an LLM-backed Agent), and emit messages or events.
- Identity: each Executor has a stable Id and handles one or more message types.
- Lifecycle:
- Receive message (often with metadata/TurnToken).
- Validate input and execute.
- Use the workflow context API to SendMessageAsync, YieldOutput, AddEvent, PostRequestAsync, ReadStateAsync, QueueStateUpdateAsync, etc.
- Emit messages/events or throw/return errors for error-routing edges.
- Best practices: single responsibility, idempotent, validate inputs early, emit structured events (start/finish/error) with TurnToken.
Edge (connection)
- Definition: a typed, directed connection between Executors. An Edge decides what happens to messages after an Executor produces them.
- Patterns:
- Direct: A → B.
- Conditional: route to B or C based on predicates.
- Fan‑out: duplicate and run in parallel to multiple Executors.
- Fan‑in/Barrier/Aggregator: collect multiple upstream messages and produce a combined downstream message.
- Error-handling: route exceptions or error messages to retry handlers, compensators, or human review.
Canonical context API (consistent names used below)
- SendMessageAsync(targetExecutorId, message): route a message to another Executor.
- YieldOutput(result): mark a final workflow result (sometimes YieldOutputAsync in async variants).
- AddEvent(event): add structured event/telemetry.
- PostRequestAsync(request): make tracked external requests.
- ReadStateAsync(key): read persisted workflow-scoped state.
- QueueStateUpdateAsync(update): request a durable state change.
- TurnToken: opaque per-turn metadata used for tracing, routing, and multi-turn state.
Executor design: concrete guidance
What an Executor should do
- Validate inputs and fail fast with meaningful, typed errors.
- Do a single logical task (classify, call retriever, synthesize).
- Use the workflow context to communicate—do not wire direct control flow to other Executors internally.
- Emit structured start/finish/error events including TurnToken or trace ID.
Idempotency and state
- Design Executors to be safe for retries. Typical pattern:
- On start, compute a deduplication key (e.g., workflowId + executorId + messageHash).
- Read state (ReadStateAsync) to see if work was already completed.
- If not completed, perform work, QueueStateUpdateAsync to mark completion, and then emit messages.
- Persist minimal state: a status flag and result reference are often sufficient.
Timeouts and cancellation
- Always accept and propagate cancellation tokens to external calls (HTTP, SDKs, LLM clients).
- Use timeouts at two levels: individual Executor calls (short) and overall wait/aggregation for fan‑in (configurable longer).
- On timeout, emit a structured error event and let an error-edge handle retries or human escalation.
There are a variety of types of workflows, which will be discussed in future blog posts.
