Skip to main content

Agents: configure and activate

The Agent Map on an agent's view page wires it to what it uses at run time and makes one version live. Read this to switch an agent on, change its wiring, read which model does what, or take it out of service.

Before you start: an execution environment must exist (a specialist cannot activate without one; Execution environments); connectors and a Ready knowledge-graph version only if the agent should use them. A supervisor takes only a version.

Steps​

  1. Open the agent and scroll to Agent Map. Idle, it reads "Configure dependencies to activate this agent. Click "Configure" to begin."; live, it shows the wiring read-only.
  2. Click Configure. The header shows Cancel, Deactivate (only when live) and Save & Activate; a control row shows Agent Version, Add Connector, Set AMPG and Set Environment (the last three are hidden for supervisors).
  3. Agent Version lists v1, v2 and so on, opening on the live version or the newest.
  4. Add Connector opens Add Data Connector: search ("Search across N connectors"), click a connector (attached ones read Already added), then in Select Version pick v1, v2 with description and date (← Back returns). A green chip such as Sales DB v2 appears with ✕ to remove it. Up to 8; then the button reads Connectors Set (max 8). No connectors yet: "No data connectors available."; see Data connectors.
  5. Set AMPG opens Set AMPG: pick a graph, then a version. Rows are newest first: v3 · Ready · 12 Sep, v4 · Building, v2 · Failed, v1 · Cancelled. Only Ready rows can be chosen; others are greyed with a tooltip such as "v4 is building". The highest Ready version is marked default and focused. A purple chip AMPG: Policies v3 appears and the button reads AMPG Set (max 1). To change graph or version, click ✕ and repeat. "Couldn't load versions for this graph." offers Retry; "This graph has no versions yet." and "No AMPGs available." point you to Knowledge graphs.
  6. Set Environment opens Set Execution Environment: rows show name, description and AlphaAgent Prebuilt or Custom Image. An amber chip Env: Python 3.12 appears and the button reads Environment Set (max 1). Without one the row shows, in red, "An execution environment is required to activate."; none exist: "No environments available."; see Execution environments.
  7. Read the map: the agent's card linked to an AMPG card, one Data Connector card per connector and an Execution Environment card; cards drag only while editing.
  8. Click Save & Activate.

What you should see​

Status reads Active, the chosen version carries the Active badge, the map shows the saved wiring read-only, and the agent appears in Chat's picker and in workflow nodes. A specialist without an environment stops with "Set an execution environment before activating this specialist agent."

If an active workflow version references the agent, This primitive is in use opens instead: the agent "is referenced by the following active workflows and cannot be modified or deleted yet", each as Name (v2), then "Open each affected workflow and detach this primitive (or activate a different version) before retrying." and, when a configuration is live, "The active workflow keeps using v2." Nothing is saved: Close, or Create a new version instead, which opens the Update Agent form prefilled (Create and optimise).

Move an agent to a new graph version​

Configure, ✕ on the AMPG chip, Set AMPG, the same graph and the new version, Save & Activate; the agent answers from it on its next run. To move every agent at once, use Move N agents here on the graph's page (Knowledge graphs: use, move agents, delete).

Deactivate​

Configure, then Deactivate, then Deactivate in the Deactivate Agent dialog. Status reads Not Active, the map returns to its idle message, the agent leaves Chat's picker, and the wiring is not kept.

Read the Model section​

Read-only: "The foundation models this deployment uses, by role." Sentences name the model id for this agent's own turns; for the board coordinator, the Governor, context summaries and PII redaction; and for knowledge-graph builds and embeddings (Supported models). "Model configuration unavailable" plus a reason means the runtime did not answer; it fills in later.

Delete an agent​

  1. Click Delete (Checking... while Studio asks which workflows reference the agent).
  2. If any do, Delete Agent? warns that deleting "will leave those workflows referencing a missing agent, which may cause them to fail", lists Affected Workflows: and offers Cancel or Delete anyway.
  3. Otherwise Delete Agent asks you to type the agent's name and click Delete. A server refusal shows inside the confirmation.

Activation is blocked while an active workflow uses the agent (create a new version instead); deletion is a warning you can override.

Notes​

RuleValue
Data connectorsup to 8, each pinned to one connector version
Knowledge graphat most 1, pinned to one Ready version
Execution environmentexactly 1 for a specialist (required); none for a supervisor
Supervisorsversion only
Active workflow references the agentactivation refused; Create a new version instead
Any workflow references the agentdeletion warned, Delete anyway
  • A red banner above the map carries the server's message when a save or deactivation fails; ✕ dismisses it.
  • The workflow check waits up to 8 seconds; if the workflow service is silent Studio proceeds without the dialog, and the server's own refusal appears in the banner or the confirmation.