Skip to main content
Version: 0.9.19

Agents

An agent is an AI assistant you define and put to work in AlphaAgent. This page covers creating an agent, the required prompt-optimization step, how versions work, wiring an agent to its data and compute in the Agent Map, activating it, and what happens when you deactivate or delete one.

What an agent is​

An agent combines:

  • Instructions — a system prompt that tells the agent its role and how to behave.
  • A type — Specialist (does focused work) or Supervisor (coordinates specialists in a swarm).
  • Wiring — an optional Knowledge Graph, one or more data connectors, and an execution environment where it runs code.

Agents are versioned: editing an agent creates a new version instead of overwriting the old one. A separate active configuration decides which version is currently live and what data and environment it uses, so editing an agent never changes what is running until you choose to activate it.

Creating an agent​

From the Agents list, click Create. You'll provide:

  1. Name and description so you and your teammates can recognize it later.
  2. Agent type — Specialist or Supervisor.
  3. System prompt — your draft instructions for the agent.

[Screenshot: Create agent form]

Knowledge graphs, connectors, and the execution environment are not chosen here — you wire those later in the Agent Map, once the agent exists.

Optimizing the system prompt (required)​

Before you can create the agent, you must run Optimize on your draft system prompt. This is a required step — the Create button stays disabled until you have optimized and locked the prompt.

When you click Optimize, AlphaAgent refines your draft into a stronger, clearer system prompt and streams the improved version back to you live. When it finishes:

  • The optimized prompt replaces your draft, and the prompt field locks to preserve it.
  • AlphaAgent may also generate an improved description and update that field; a short notice tells you when it has.
  • If you want to keep editing, click Revert to restore your original text and unlock the field. You can re-optimize as many times as you like.
  • You can Cancel an optimization while it is still streaming.

Once the prompt is optimized and locked, click Create to save the agent.

[Screenshot: System prompt optimization, locked after optimizing]

Versions​

Open an agent to see its detail screen, which includes:

  • A preview of the system prompt (expandable).
  • An Active / Not Active status.
  • An Agent Versions table listing every version, with the currently active version marked.

To edit an agent, click Update. You can change the name, description, and system prompt. Saving publishes a new version — the save button shows which version you are about to create (for example, "Saving creates v3"). Dependency wiring is not edited here; that lives in the Agent Map.

The Agent Map​

The Agent Map is a visual editor on the agent's detail screen where you connect an agent version to its data and compute, then make that configuration live.

[Screenshot: Agent Map editor]

In view mode the map shows the saved active configuration. Click Edit Map to make changes, or Cancel to discard them and return to the saved configuration. While editing you:

  • Pick the agent version to activate (defaults to the active version, or the latest).
  • Attach a Knowledge Graph — at most one. You choose the graph and then a specific version of it.
  • Attach data connectors — up to 8. For each, you choose the connector and a specific version.
  • Attach an execution environment — exactly one.

Each attachment pins a specific version, so your live agent keeps using the version you selected even if you later publish new ones.

Save & Activate​

When the wiring is ready, click Save & Activate to make this the agent's live configuration. Two rules apply:

  • Specialists must have an execution environment. If you try to activate a Specialist without one, Save & Activate is disabled with a reminder to set an environment first. (Supervisors don't require one.)
  • Agents in use by a workflow are protected. If the agent is referenced by an active workflow, Studio blocks the activation and shows which workflows are affected. Detach the agent from those workflows first, then activate.

Deactivating and deleting​

Deactivate​

Deactivating an agent takes it out of service. Before it does, Studio checks for impact: if the agent belongs to any swarms, a confirmation lists those swarms so you understand what will be affected before you proceed.

Delete​

Deleting checks for impact first. If the agent is referenced by any swarms or workflows, Studio shows a guard listing them and does not delete — you resolve those references first. If nothing depends on the agent, a confirmation lets you delete it.

This impact-aware behavior keeps live swarms and workflows from breaking when an agent they rely on is removed.