Agents & Activations (SDK)¶

Why This Page Exists¶

An activation is a named, tenant-scoped instance of an agent: it carries configuration, starts that agent's activable workflows, and appears in workflow IDs as idPostfix. Agent Studio and the Admin API can create and toggle activations — and so can agents themselves, via the SDK, under certificate auth.

This page covers the runtime APIs for inspecting and managing agents/activations in the current tenant: checking whether another agent exists, creating and activating it, verifying status, listing activations, and deactivating. For how activation context flows when starting another agent's workflow, see Cross-Agent Workflows. For the product lifecycle (template → deploy → activate), see Multitenancy.

graph LR
  A["XiansAgent"] -->|".Tenant"| T["TenantAgents"]
  T -->|.Agent(name)| R["AgentReference"]
  A -->|self checks| S["GetActivationStatusAsync / ActivationExistsAsync"]
  R -->|ExistsAsync| E1["GET agents/exists"]
  R -->|status / list / create| E2["GET/POST activation"]
  R --> I["ActivationInfo"]
  I -->|ActivateAsync / DeactivateAsync| E3["POST activation/id/..."]

Two Entry Points¶

The target agent does not need to be registered in the same process. Calls use the calling agent's HTTP client and certificate; for system-scoped callers, the acting tenant comes from context (XiansContext.SafeTenantId) with a fallback to the certificate tenant.

Checking Your Own Activation¶

When running inside a workflow or activity, the activation name defaults to the current idPostfix:

var agent = XiansContext.CurrentAgent;

// Current activation from context
bool active = await agent.ActivationExistsAsync();
var status = await agent.GetActivationStatusAsync(); // Active | NotFound | Deactivated

// Or pass a name explicitly (also required outside workflow/activity context)
bool euActive = await agent.ActivationExistsAsync("fraud-detection-eu");

ActivationExistsAsync is true only for Active. Missing or deactivated both return false. Real errors (missing HTTP service, 400, 5xx) still throw.

Inspecting Another Agent¶

var other = agent.Tenant.Agent("Fraud Detection Agent");

// Dedicated agent-exists endpoint (no activation name required)
bool agentExists = await other.ExistsAsync();

// Activation status for that agent
var status = await other.GetActivationStatusAsync("fraud-detection-eu");
bool activationActive = await other.ActivationExistsAsync("fraud-detection-eu");

Managing Activations (Create / Activate / List / Deactivate)¶

Full lifecycle against another agent (or yourself via Tenant.Agent(agent.Name)):

var other = agent.Tenant.Agent("Activation Target Agent");

if (!await other.ExistsAsync())
    throw new InvalidOperationException("Target agent is not deployed in this tenant.");

// Create is inactive until you activate
var created = await other.CreateActivationAsync(
    name: "sdk-demo",
    description: "Provisioned by orchestrator");

// Starts the target's activable workflows under this activation name
await created.ActivateAsync();

// Or by id:
// await other.ActivateAsync(created.Id);

var listed = await other.ListActivationsAsync();
foreach (var a in listed)
    Console.WriteLine($"{a.Name} id={a.Id} active={a.IsActive}");

// "Remove" on the Agent API today means deactivate (cancels workflows; record remains)
await created.DeactivateAsync();
// await other.DeactivateAsync(created.Id);

CreateActivationAsync parameters¶

Create returns an ActivationInfo that is bound to the AgentReference, so you can call ActivateAsync / DeactivateAsync on the handle without juggling ids.

ActivationInfo (handle)¶

Optional workflow configuration can also be passed at activate time:

await created.ActivateAsync(workflowConfiguration:
[
    new WorkflowConfig
    {
        WorkflowType = "Activation Target Agent:Heartbeat Workflow",
        Inputs = [new WorkflowInputValue { Name = "region", Value = "eu" }]
    }
]);

End-to-End Pattern (Activity)¶

[Activity]
public async Task ProvisionAsync()
{
    var manager = XiansContext.CurrentAgent;
    var target = manager.Tenant.Agent("Activation Target Agent");

    if (!await target.ExistsAsync())
        throw new InvalidOperationException("Target agent missing.");

    var activation = (await target.ListActivationsAsync())
        .FirstOrDefault(a => a.Name == "sdk-demo")
        ?? await target.CreateActivationAsync("sdk-demo");

    if (!activation.IsActive)
        activation = await activation.ActivateAsync();

    if (!await target.ActivationExistsAsync("sdk-demo"))
        throw new InvalidOperationException("Activation did not become active.");
}

A runnable two-agent sample (manager provisions a target's activation, waits while the target heartbeats, then deactivates) lives in the Xians.Examples/ActivationManagement project.

Relation to Cross-Agent Workflow Starts¶

Passing activationName to start/execute validates that the activation is active (or throws ActivationNotFoundException / ActivationDeactivatedException). Use the management APIs on this page when you need to provision that activation first.

API Reference¶

XiansAgent (self)¶

TenantAgents / AgentReference¶

Related¶

• Multitenancy — template → deploy → activate product model
• Cross-Agent Workflows — starting/signaling workflows under an activation
• Agents — registering agents and activable custom workflows
• Messaging – Webhooks — self activation checks before managing webhooks