The Graph Is the Program: Blocks, Pins, and Contracts
In AutoGPT, the graph is the executable structure that turns a collection of AI and software actions into an agent. This chapter focuses on the contract between blocks and on the data conditions that let one block activate another, so readers can predict a workflow from its wiring and design both a useful output path and a deliberate failure path.
A block is a typed contract
A block is not simply a button that calls a model or an external API. It is a component with a defined input schema, a defined output schema, and an execution method. The schema says what the component expects and what it may produce; the execution method performs the action and yields named outputs. AutoGPT uses those schemas to expose the block to the visual builder, validate graph connections, and check the values that arrive at run time.
The word schema means a machine-readable description of data. If a block expects a text prompt, the schema can identify that value as text. If it returns a list of records, the schema can describe a list and the shape of its items. The Platform turns its Pydantic-based schemas into JSON Schema so the same contract can be used by the backend and by interfaces that need to render fields. This is why the pins on the canvas are more than connection points: they are named ports with expected data shapes.
The contract has several parts that matter to a workflow author:
- Inputs identify the values a block needs. Some are required, while others have defaults or advanced settings.
- Outputs identify the values a block can yield. A block may return more than one named result.
- Types restrict which values can be connected safely. The Platform documents text, numbers, files, lists, booleans, and objects among its common types.
- Metadata describes the block and can also carry behavior such as categories, cost rules, webhooks, or a time limit.
- Errors are part of the standard output vocabulary for ordinary blocks, giving the workflow a place to represent failure.
This contract makes a visual graph closer to a dataflow program than to a slide showing a process. A block can still contain sophisticated code or an unpredictable model call, but the boundary around that action is explicit. The graph can check whether a required value is present and whether the connection names a real input or output. It cannot decide whether a generated answer is wise, or whether an external service will accept a request. Those are semantic and provider-level questions, not type checks.
Public inputs, internal actions, and visible outputs
AutoGPT uses special Input and Output blocks to separate an agent's public interface from its internal construction. An Input block has a name and a value. The name becomes the label that a person sees when they start a task, while the value is passed into the graph. An Output block has a name and a value to record. Its name becomes the key under which the result is shown to the person who ran the agent.
That distinction matters because the visible workflow and the user-facing contract are not the same thing. Consider a small question-and-answer agent. The graph might contain an Input block named question, an AI Text Generator block that receives that value as its prompt, and an Output block named answer. The person running the agent fills in one question and receives one answer. They do not need to know which intermediate block produced the text, what internal prompt formatting occurred, or how the builder represents the connection.
The internal action still matters, but it has a different responsibility. It must accept the data supplied by the graph and produce an output that conforms to its declared schema. The graph author decides which output pin feeds the next block and which values are fixed directly on a node. The public Input and Output blocks define the boundary; the internal blocks define how the agent crosses it.
This also explains why a graph can be reused without being identical in every context. A workflow that exposes topic and summary can be placed inside a larger process whose upstream block supplies the topic. A different workflow can connect its summary to an email, a document, or another agent. The public contract stays meaningful even when the surrounding graph changes. Reuse comes from preserving the relationship among inputs, actions, and outputs, not from copying an opaque conversation transcript.
The Platform validates these relationships at two levels. Graph validation checks structure: a link must point to existing nodes and valid pins, and required fields must be connected or configured where the graph is being prepared for a run. Execution validation checks the actual values after defaults and upstream results have been applied. A graph can therefore be structurally valid and still fail at run time because a provider rejected a credential, a user supplied an invalid value, or an action produced an unexpected result.
The important relationship in the diagram is not the class names. It is the direction of responsibility. A graph contains nodes and links. A node selects a block and stores defaults. A block validates inputs and yields named outputs. Input and Output blocks turn those internal contracts into the agent's public schema. A link carries a value from one named pin to another, and its static setting changes how that value may be reused.
Readiness is a data condition, not a position on the canvas
The canvas may encourage a left-to-right reading, but AutoGPT does not use visual position as the execution order. Execution begins from each starting point: an Agent Input block, or an executable block with no inbound links. A downstream block becomes eligible when its required inputs are available and valid after upstream outputs and configured values have been combined.
Suppose a calculator block needs two numbers, a and b. If two Input blocks feed those pins, the calculator waits until both values are present. If a is connected but b is hardcoded on the calculator, the hardcoded value satisfies that requirement. If an input is required but has neither a valid connection nor a configured value, the graph should not treat the block as ready. This rule gives the graph a predictable initial condition: a node runs because its data contract is satisfied, not because it happens to appear next in a drawing.
The same rule explains why independent branches can proceed without an artificial sequence. Imagine a report agent that retrieves a calendar and a weather forecast before a later block combines them. Neither retrieval needs the other's result, so both can be considered independently. The combining block must wait for the values it consumes. The runtime may execute the independent work in either order, or concurrently within its worker limits, but it cannot legitimately combine data before the dependencies are available.
Typed pins add another guardrail. A text result can connect to a text prompt, while a number, file, list, or object may require a compatible destination or a deliberate transformation. Type compatibility does not guarantee that the value makes sense. A string containing a date might pass a broad text schema but still be unusable to a provider expecting a particular date format. The schema narrows the space of possible mistakes; it does not replace domain validation.
The Platform also distinguishes ordinary links from static links. A normal connection carries an output into a downstream input as part of an execution. A static connection can provide a value that is reused when later executions of a downstream node need it. This is useful for a configuration or a shared value that should remain available while another input changes. It is dangerous if the author assumes that every output is automatically reusable, because a repeated workflow may otherwise consume data differently from what the diagram suggests.
A list introduces a related choice. A block may emit a list as one value, allowing a downstream block to process the collection as a whole. Or an iteration block can yield individual items, so the downstream action runs once for each item. Consider a workflow that fetches several URLs and then extracts their contents. Passing the list to a batch-aware action asks that action to handle the collection. Inserting an iterator makes each URL a separate item in the flow. The choice affects output cardinality, cost, error isolation, and the meaning of a later aggregation step.
The graph therefore has two kinds of shape to keep in mind. The first is structural shape: which nodes are connected and what each pin accepts. The second is execution shape: how many values travel across those links and whether a value is reused, consumed, or expanded into multiple executions. Two graphs may look similar while producing very different numbers of downstream actions if one passes a list and the other iterates over it.
Error behavior belongs in the design
A workflow that only specifies its successful path is incomplete. AutoGPT's data-flow guidance says a failed block produces data on an error pin rather than automatically stopping the entire agent. The author decides what to do with that result. An error can be connected to an Output block so the task reports the failure, routed to a fallback action, or left unpropagated so dependent normal-output paths do not continue.
Imagine a research agent that calls a search provider and then asks a model to summarize the returned sources. If the search action fails because the provider is unavailable, blindly sending an empty value to the summarizer can create a misleading “successful” report. A deliberate graph can instead connect the error to an output that says the report is unavailable, or route it to an alternate search path. If a missing result is genuinely optional, the graph may allow the rest of the workflow to proceed without that branch.
The distinction between an error result and a terminal graph failure is important. A block-level error describes what happened at one action boundary. The graph-level policy determines whether that event should be visible, handled, or allowed to make the overall task fail. A later runtime chapter will examine how the executor persists these outcomes. At the graph level, the practical rule is already clear: do not assume that a failure will be handled intelligently unless a connection or a platform policy gives it somewhere to go.
There is a second subtlety in the block contract. The Platform validates ordinary outputs against the declared output schema, and the execution layer turns certain raised or yielded errors into block execution failures. A block that returns data with the wrong shape is not merely “a little inaccurate”; it violates the interface that downstream nodes rely on. Conversely, a validly shaped output can still carry a wrong conclusion. Robust graph design needs both contract validation and domain-appropriate checks.
This is why incremental testing is more useful than drawing a large graph and hoping the final run explains it. Start with the public inputs and outputs. Confirm that each connected value has the expected type and that required fields are satisfied. Run a small path, inspect what the Output block receives, and then add a branch or an iterator. During development, surfacing errors at an Output block can make a hidden failure visible before the workflow grows more complicated. Later, the same error can be routed to a user-facing fallback or a recovery action.
The contract sets the limit of predictability
The graph gives AutoGPT a concrete program to validate: named inputs, typed pins, configured defaults, downstream dependencies, list behavior, and explicit outputs. That is a stronger basis for prediction than a single prompt asking a model to “handle everything.” It also makes the agent reusable, because another context can supply the same contract with different values or connect the result to a larger workflow.
But predictability stops at the boundary of each block. A model may produce a plausible but incorrect answer. An API may reject a validly shaped request. A file may be unavailable, a credential may not authorize the requested action, or an external event may never arrive. The graph can represent those possibilities and route their consequences; it cannot make outside systems deterministic.
The next problem is therefore temporal. Once the graph has a valid starting input, how does AutoGPT turn that definition into a live task? The answer involves separate graph and node execution records, queues, workers, event streams, and state transitions. Understanding those runtime mechanisms shows what the Platform can remember about a run—and what happens when progress is partial rather than complete.