> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegradient.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents and topology

> How Gradient models an agent as a topology of single-prompt nodes, with handoffs that are themselves callable tools.

The core primitive is the single-prompt node, and an agent is a topology of them. The pieces are deliberately small: a node is a prompt and its tools, and control moves between nodes through handoffs you can see on the canvas.

## The single-prompt node

A node is one model, one system prompt, and the tools that model can call. It has:

| Field             | What it is                                                                                            |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| **Key**           | A stable identifier for the node inside the agent. Handoffs and traces address the node by its key.   |
| **Label**         | A human-readable name for the node on the canvas.                                                     |
| **Description**   | What the node is for.                                                                                 |
| **Model**         | The model binding, written as `provider:model`, for example `openai:gpt-4.1`.                         |
| **System prompt** | The instructions that steer the model while control sits on this node.                                |
| **Tools**         | What the model can do from the node: hand off, end the call, call your code, or make an HTTP request. |

A node can also carry any **skills** and **knowledge bases** you attach to it. See [Knowledge and skills](/build/knowledge-and-skills).

## An agent is a topology

An agent is a set of nodes wired into a graph. One node is the **entrypoint**. Every conversation starts there. Each node steers the conversation with its own prompt and tools until it hands off to another node or ends the call.

```mermaid theme={null}
flowchart TD
    T["triage<br/>entrypoint"]
    L["patient_lookup"]
    E["existing_patient_scheduling"]
    N["new_patient_scheduling"]
    P["prescription_refill"]
    X(["end_call"])

    T -->|"continue_to_lookup"| L
    L -->|"continue_to_existing_patient_scheduling"| E
    L -.->|"continue_to_new_patient_scheduling"| N
    L -.->|"continue_to_prescription_refill"| P
    E --> X
```

Here `triage` is the entrypoint. Each labeled edge (`continue_to_lookup`, `continue_to_existing_patient_scheduling`) is a handoff the model can call to move control.

## Handoffs are tools

An edge is not a separate kind of thing. A handoff is a callable tool: an `agent_swap` tool on the source node whose target is named as a pair, `target_key` and `target_version`. Pinning the target version means a graph that is already serving traffic cannot be changed by a later draft edit.

The tool's description is the sentence the model reads to decide whether to take the path. Write it the way you would explain the transition to a teammate: "the caller is an existing patient and wants to schedule."

The consequence is the important part: if a handoff is not present as a tool on a node, the agent cannot take that path. The canvas and the runtime are the same data, so what you can see is exactly what the model can do.

<Note>
  Publishing an agent freezes the entrypoint and every node reachable from it through handoffs. A node with no handoff pointing at it is unreachable, and it is left out of the published version.
</Note>

## Nodes are addressed by key

Every node has a stable **key**, and handoffs, transcripts, and the engine all speak in keys, never row IDs.

The reason is publishing. The draft is mutable; publishing copies the reachable draft into a new, immutable revision with new rows and new IDs. A row UUID is only valid until the next publish, but a key is stable for the life of the node. See [Versions](/publish/versions).

## Building in the dashboard

The agent builder is fully editable. You can:

* create and delete nodes, and edit prompts and model bindings
* wire handoffs between nodes
* attach deployed [custom tools](/build/custom-tools), [skills, and knowledge bases](/build/knowledge-and-skills)
* chat with the latest published version and inspect its traces

<CardGroup cols={2}>
  <Card title="Tools" href="/build/tools">
    The four tool shapes a node can carry, and how they attach and run.
  </Card>

  <Card title="Versions" href="/publish/versions">
    How the mutable draft becomes an immutable, numbered published version.
  </Card>
</CardGroup>