# 2. BehaviorGraphAgent and the Blackboard
Part of [[Unity Behavior]]. Prev: [[1. Graphs versus the Existing FSM]]. Next: [[3. Authoring Graphs and Custom Nodes]].
## 2.1 Install
Package Manager > Unity Registry > **Behavior** (`com.unity.behavior`). Official 6000.5 page: **1.0.17** released; **1.0.16** also listed. Pin what you test. This series follows the **1.0.17** manuals.
Create a graph asset from the official Create menu in the Project window (Create > Behavior > … — confirm the exact menu caption in 1.0.17; do not invent a path). Open it in the Behavior graph editor.
## 2.2 Add an agent (official steps)
Official [Behavior Agent](https://docs.unity3d.com/Packages/
[email protected]/manual/behavior-agent.html) manual (1.0.17):
1. Select the GameObject.
2. Add Component > **Behavior Agent** (`BehaviorGraphAgent`, menu `AI/Behavior Agent`).
3. Assign a **Behavior Graph**.
Alternatively: drag a behavior graph asset onto the GameObject; Unity adds the component and links the graph.
Official note: if you need an agent that **starts disabled**, disable `BehaviorGraphAgent` at creation, then enable it when you want it to process. Enabling and disabling the component is the official pause / resume.
Enter Play mode to preview.
## 2.3 Lifecycle (official)
`BehaviorGraphAgent` official states: **Uninitialized** → **Initialized** (unique copy of the graph for this agent) → **Started** → **Running** (updated each frame) → **Ended**.
Initialization, official:
- Graph assigned in the Inspector: initialized during `Awake()`.
- Graph assigned to the `Graph` property at runtime: marked uninitialized and initialized on the **next `Update`** if the agent is enabled. Official: you do **not** have to call `Init()` or `Start()` just because you set `Graph`.
- You may call **`Init()`** yourself to control timing. Official: if the agent is already initialized, `Init()` clones a **new** instance of the assigned graph and restarts execution.
Official runtime-lifecycle manual: the agent acquires a runtime instance from the source graph, starts and updates it while the component is active, and stops and releases the instance when the graph is replaced or the component is destroyed.
## 2.4 Blackboard: overrides vs instance values
Official `SetVariableValue` timing:
- **Before** initialization: sets **agent-level overrides** (visible in the Inspector). Useful as defaults on a prefab / template.
- **After** initialization: sets values on **this instance's** blackboard.
```csharp
using Unity.Behavior;
using UnityEngine;
/// <summary>
/// Assigns a graph and a per-instance blackboard value.
/// NOT compiled in Unity; not play-tested in Play mode.
/// </summary>
public sealed class GuardAgentBootstrap : MonoBehaviour
{
[SerializeField] BehaviorGraphAgent agent;
[SerializeField] BehaviorGraph graph;
[SerializeField] Transform patrolAnchor;
void Start()
{
// Template-style default before Init (override), then a unique value after.
agent.Graph = graph;
agent.SetVariableValue("Speed", 3.5f);
agent.Init();
agent.SetVariableValue("PatrolAnchor", patrolAnchor);
}
}
```
`SetVariableValue` and the `"Speed"` / `"PatrolAnchor"` strings must match **blackboard variable names** on the graph. Typo'd names fail silently or return false, depending on the overload you use — confirm the 1.0.17 signature in IntelliSense (`SetVariableValue` is official; a `GetVariable` out-parameter pattern is in the bind-from-C# manual).
## 2.5 Exercise
Create an empty graph with a blackboard float `Speed` and a `GameObject` or `Transform` variable (use the types the 1.0.17 blackboard UI actually offers). Add a `BehaviorGraphAgent`, run the bootstrap, and confirm in the Inspector that the instance value is the one you set after `Init()`.
## Sources
- https://docs.unity3d.com/Packages/
[email protected]/manual/behavior-agent.html
- https://docs.unity3d.com/Packages/
[email protected]/manual/runtime-lifecycle-overview.html
- https://docs.unity3d.com/Packages/
[email protected]/api/Unity.Behavior.BehaviorGraphAgent.html