designs - typescript - graph

[pgrayy]

Description

Related Issues

Type of Change

• New content
• Content update/revision
• Structure/organization improvement
• Typo/formatting fix
• Bug fix
• Other (please describe):

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using mkdocs serve
• Links in the documentation are valid and working

---

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

[zastrowm]

Should we have INTERRUPTED for future usage?

[pgrayy]

It'll be included in v1. I only gave the blurb about it in the overview because there is already a lot of content in this doc to discuss.

[JackYPCOnline]

interrupt is a follow up?

[pgrayy]

Yes correct. It'll follow the same pattern as Python though which already went through a design review.

[zastrowm]

so customers get compile-time type safety and runtime validation without writing generics

Can you expand on this a bit? Whereis/what is schema coming from in this case?

Wondering if AgentState should be using the same pattern

[pgrayy]

The schema is passed in by the user into the GraphBuilder. This will then give users a well typed state object they are free to manipulate in code through node functions, hook callbacks, etc.

An alternative approach I considered was using generics, but that became cumbersome because it would require making everything above MultiAgentState generic as well.

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-543/

[zastrowm]

Might be worth having input on here for completeness TBH

[pgrayy]

We could. NodeInput, NodeState, and NodeResult are meant to be flexible and actually could share fields with one another. I actually wanted to consider combining everything into NodeState and will discuss that afterward. For now though, I think this is a good start because it mirrors what we did in Python.

[JackYPCOnline]

Question : What is the trade off vs timestamp here

[pgrayy]

timestamp is a point in time where duration is a time delta. timestamp would be something like a DateTime type where as duration would be a number measuring seconds.

[JackYPCOnline]

yes I mean we expose start & finish time instead of duration. user can have more extensibility if there is a use case.

[dbschmigelski]

So does this mean in addNode we are going to add sugar so you can pass in Node or Agent and we'll just wrap as needed? Or are we making Agent actually implement Node

[pgrayy]

We wrap the Agent instance into an AgentNode instance on behalf of the customer.

[zastrowm]

nit: we should normalize/standardize on a duration of some sort

[pgrayy]

Agreed. We did not do this in Python. There are multiple duration fields where some are measured in seconds, others in milliseconds. Here I figured seconds was a good standard.

[mehtarac]

should we track the parent node? would be None for the entry point node

[pgrayy]

I'm not sure we need to track it in result. Users can already see the graph structure directly going through graph.state and graph.config. But could be added here if there is a good reason. It is an additive thing which is backwards compatible.

[Unshure]

What proposed changes here are different than what we have in python?

[Unshure]

nit: Should this be more general?
https://github.com/strands-agents/sdk-typescript/blob/main/src/agent/agent.ts#L118

[pgrayy]

Yes this can be extended and made more general. We could use invokeArgs for the time being, but I figured I would consider a NodeInput incase we wanted to expand even further. But for now, probably worth replacing with InvokeArgs. Same for GraphInput. Could be replaced by InvokeArgs.

[Unshure]

nit: Should all of these be their own add...() functions for the builder?

[zastrowm]

FWIW, I have not seen the builder pattern much in JS/TS.

---

IMHO the add methods would be just noise vs making it a config option

[zastrowm]

Is there a way that external things can contribute? I'm thinking if you add a hook, what's the mechansim for a hook to add state as well that doesn't necessarily match this schema? Should that be allowed and/or is that desirable?

[mehtarac]

retry:? whether on timeout or error

[pgrayy]

Yeah we can add retry configs here. NodeConfig is setup to be additive so any more ideas you have pitch them.

[JackYPCOnline]

Agent as Node, Function and Multiagent as Node use same NodeConfig interface.
Anything else we should include?

[pgrayy]

We could create a MutliAgentNodeConfig or AgentNodeConfig if need be but right now I'm not seeing a use case. But they would extend NodeConfig if we decided on it.

[mkmeral]

Can we get the multiagent interface to match the agent one? From python, I think MultiAgentBase is pretty much the same as AgentBase, and I was thinking about getting rid of one

[zastrowm]

👍 had a similar question.

[mkmeral]

Do we plan to do AgentBase for other remote agents?

[dbschmigelski]

High level

This doc does a good job of telling us what we are doing. But it feels like the onus is on the reader to figure out how this differs from the python implementation. I think it would be helpful to call out early and explicitly exactly what we are changing (or potentially controversially keeping) compared to the existing impl.

For example, are we keeping the (questionable) OR edge logic we use in python, or are we going to use AND for consistency?

[mkmeral]

(outside scope of this doc) one thing i'd like to see is how we can actually get rid of the tool injection logic. I don't like that swarm is so intrusive.

Probably we should switch to structured output

[zastrowm]

What's in MultiAgentBase? Is the a world in which we ditch MultiAgentBase and just do AgentBase? In Python I think MultiAgentBase just includes serialize_state & deserialize_state and maybe those go on Agentbase instead? (almost like a snapshot)

[mkmeral]

Can we have a list of node results? This is one of the limitations we had with initial version of the graph. It didn't allow for cycles so each agent can have a single result.

With the cyclic graphs, each agent can generate multiple node results

[mehtarac]

high level q: Is there any deviation in the dev ex of using graphs in ts vs python?

[pgrayy]

Slight deviations yes. Apologies I didn't have time to include in the doc. I'll address after review.

[mkmeral]

again for cyclic graphs. what if one execution succeeded and one failed?

this is pretty annoying for Python bc we had to think about backwards compatibility with the already established data types/classes

[zastrowm]

Have we considered alternative/simpler devx's?

GraphBuilder.build(
  flows: [
    [ researcher, writer],
    [ writer, reviewer],
    [ reviewer, writer, (state) => !state.user.approved],
    [ reviewer, formatOutput, (state) => !state.user.approved],
  ],
  options: {
    maxNodeExecutions: 10,
    executionTimeout: 60,
    userSchema: z.object({
      drafts: z.number().default(0),
      approved: z.boolean().default(false),
    }),
  }
)

or even

GraphBuilder.build(
  flows: [
    [ researcher, writer, reviewer],
    [ reviewer, writer, (state) => !state.user.approved],
    [ reviewer, formatOutput, (state) => !state.user.approved],
  ],
  options: {
    maxNodeExecutions: 10,
    executionTimeout: 60,
    userSchema: z.object({
      drafts: z.number().default(0),
      approved: z.boolean().default(false),
    }),
  }
)

[JackYPCOnline]

We get rid of any for sure right

[mkmeral]

so this is OR logic on edges, then?

[mkmeral]

nit: if we are doing builder pattern, i'd expect the configs to be set-able on the builder directly, i.e. builder.set_timeout()

[zastrowm]

We can explore this, but I am curious on the repercussions; this would lean more towards returning a state "object" rather than having state on the graph/swarm

For graphs/swarm this might make a lot of sense to start with off the bat - though a POC would help here

[zastrowm]

This differs from RemoteAgent in that it elevates the concept of remote execution outside of an agent? I like the idea.

There's nothing preventing this today in Python is there? Assuming we support it via FunctionNode?

[zastrowm]

Referencing by id/name is odd IMHO; why not pass the object itself

[zastrowm]

For extensibility I'd suggest:

Suggested change

	.addEdge('reviewer', 'writer', (state) => !state.user.approved)
	.addEdge('reviewer', 'writer', ({state}) => !state.user.approved)

But otherwise like elevating this here

[mkmeral]

TS vs Python Diff (what Kiro says)

Don't take it at face value, this is to augment the offline conversation right now

Comparison of the TS graph design against the current Python multiagent/graph.py implementation.

Node Architecture — Polymorphic hierarchy vs isinstance branching

Python uses a single GraphNode dataclass with executor: AgentBase | MultiAgentBase and dispatches via isinstance checks in _execute_node (~50 lines of branching).

TS introduces a polymorphic hierarchy: abstract Node → AgentNode, MultiAgentNode, FunctionNode. Each subclass implements _stream(), and the base stream() handles boilerplate (duration, status, error handling). The graph engine calls node.stream() uniformly — no type-checking needed.

FunctionNode is new — it wraps plain/async/generator functions via NodeHandler, enabling transformation, routing, and side-effect nodes without wrapping everything in an Agent. This is a gap in the Python SDK.

Execution Model — Eager vs batch-based

Python uses batch execution: nodes in a batch run in parallel via asyncio.Queue, then after the entire batch completes, newly-ready nodes are discovered and form the next batch.

TS uses eager execution: as soon as any node completes, downstream nodes that are now ready start immediately. No waiting for batch siblings.

This matters for graphs with mixed-latency nodes — in Python, a fast node in batch N+1 waits for all of batch N to finish, even if its specific dependency completed early.

TS also adds maxConcurrency to limit parallel node execution, which Python doesn't have.

Failure Semantics — Graceful vs fail-fast

Python is fail-fast: exceptions propagate up, sibling tasks in the same batch are cancelled immediately.

TS captures errors in NodeResult instead of throwing. Concurrently running nodes are allowed to finish (graceful exit). The graph is marked FAILED if any node fails. Downstream dependents of the failed node stay PENDING. Customers can override for fail-fast behavior.

TS also adds CANCELLED status and graph.cancel() for explicit graceful cancellation, which Python doesn't support.

User State — Typed via Zod vs no equivalent

TS introduces MultiAgentState.user typed via Zod schema inference (z.infer<typeof schema>), giving compile-time type safety and runtime validation. Customers pass userSchema in GraphConfig and mutate state.user directly from edge conditions and function nodes.

Python's GraphState has no user-defined state section. Edge conditions receive the full GraphState but there's no structured way to carry custom state across nodes.

Agent State Isolation

TS AgentNode always captures and restores agent messages/state per execution — the same agent instance can run multiple times without carrying over conversation history.

Python requires opting in via reset_on_revisit on the builder. Without it, revisited nodes accumulate state from prior executions.

Builder API — Config object vs setter methods

Python uses individual fluent setters: set_max_node_executions(), set_execution_timeout(), set_node_timeout(), set_graph_id(), etc.

TS consolidates into a single GraphConfig object passed to build():

.build({
  maxNodeExecutions: 10,
  executionTimeout: 60,
  maxConcurrency: 5,
  userSchema: z.object({ ... }),
})

Both auto-detect entry points (nodes with no incoming edges). Python additionally allows explicit set_entry_point().

Streaming Events — Typed objects vs dicts

Python yields plain dicts (events call .as_dict() before yielding).

TS yields typed event objects with discriminated unions via the type field, enabling pattern matching:

if (event.type === 'multiAgentNodeStartEvent') { ... }

Features in Python not covered by TS design (intentionally deferred)

• Interrupts (_InterruptState, interrupt resumption, MultiAgentNodeInterruptEvent)
• Session management (serialize_state / deserialize_state, SessionManager)
• Hooks (BeforeNodeCallEvent, AfterNodeCallEvent, BeforeMultiAgentInvocationEvent, etc.)
• OpenTelemetry tracing

The design doc explicitly states these follow existing SDK patterns and don't need separate design discussion.

Features in TS design not in Python

• FunctionNode for arbitrary function/async/generator nodes
• Typed user state via Zod schema
• maxConcurrency limit
• graph.cancel() for graceful cancellation
• Graceful failure handling (errors in results, concurrent nodes finish)
• Eager execution model
• RemoteNode as a future consideration

[zastrowm]

In general I think we should prefer objects as arguments instead of individual arguments:

Suggested change

	type NodeHandler = (input: NodeInput, state: MultiAgentState) => NodeHandlerResult | Promise<NodeHandlerResult> | AsyncGenerator<MultiAgentStreamEvent, NodeHandlerResult, undefined>
	type NodeHandler = ({input: NodeInput, state: MultiAgentState}) => NodeHandlerResult | Promise<NodeHandlerResult> | AsyncGenerator<MultiAgentStreamEvent, NodeHandlerResult, undefined>

Allows folks to pick and choose and allows us to extend in the future