Agents

The Agents dashboard (/dashboard/agents) is Suvra's registry of every autonomous actor that calls validate / execute. Agents register through the SDK or the HTTP API; the dashboard focuses on editing post-registration settings such as policy assignment, workspace path, node binding, and runtime metadata.

Requires agents.read to view; agents.write to edit; policies.write to push a policy refresh.

Agent list

Each card shows:

• Agent Name (falls back to agent_id)
• Agent ID
• Owner (if set)
• Node ID (if bound)
• Policy — link to policy detail, or "SuvraPolicy only"
• Edit Settings button opens the detail form

Registration

Required parameter

Recommended parameters (optional)

All of these fields participate in the policy context and the approval params_hash, so changing them affects future decisions and approval reuse integrity.

Via SDK (most common path)

Registration happens once at SDK init — the client auto-registers on first call via PUT /agents/{agent_id}/register and then heartbeats.

from suvra import Suvra

guard = Suvra(
    url="http://your-suvra-server",   # remote mode
    agent_id="my-agent-001",          # REQUIRED
    agent_name="My Agent",
    framework="anthropic",
    purpose="Handles customer support queries",
    risk_tier="medium",
    tools_used=["web_search", "database_query"],
    data_classes_touched=["PII", "financial"],
    policy_id="policy-prod-001",
)

Via HTTP API

Deployment pipelines can pre-register via the REST API:

• PUT /agents/{agent_id}/register — upsert
• POST /agents — create only

Environment variable auto-resolution

If you don't pass these explicitly, the SDK resolves them automatically:

Validation rules

• agent_id — empty string or None raises ValueError; duplicate raises DuplicateAgentError
• integration is a synonym for framework — if framework is missing, the system falls back to integration
• List fields (tools_used, data_classes_touched, environment_access) accept CSV strings or Python lists — normalized automatically
• status defaults to "active" at the storage layer if not set
• If a licensing service is configured, tenant_id is validated against license limits before creation

Important note on framework integrations

The framework integration wrappers (suvra/integrations/) do not handle registration — they handle action-level enforcement after registration. Registration is done once at SDK init or via the /agents API.

Edit form

The detail form is grouped into three sections:

Identity

• Agent Name
• Owner
• Purpose

Runtime

• Workspace Path (writes workspace_dir)
• Node (dropdown of registered nodes)
• Framework / Integration
• Runtime Type
• Status (Active / Disabled)

Security

• Risk Tier
• Approval Profile
• Policy (dropdown of agent policies, or "SuvraPolicy only")

Buttons: Update Agent, Cancel, Push Policy Update.

Push policy refresh

Push Policy Update enqueues a refresh_policy command in the agent's commands_queue. The agent picks up the command on its next heartbeat and refreshes its bound policy. In distributed deployments, the equivalent flow for nodes is a signed bundle push — see Nodes.

Deterministic registry precedence

• If an action includes agent_id and the agent exists, Suvra fills missing action context from the registry before policy evaluation
• Explicit request-supplied values always win field by field
• If agent_id is absent or not registered, Suvra keeps the existing action-only behavior

Policy-accessible registry-derived context includes agent_id, risk_tier, approval_profile, integration, runtime_type, owner, purpose, and status.

Billing impact

• Only agents with status=active count toward license limits and billable usage
• Disabled or deleted agents do not count
• The first active agent is always free from a billing standpoint

RBAC

• View: agents.read (Viewer+)
• Create / edit: agents.write (Policy Admin, Admin)
• Push policy: policies.write (Policy Admin, Admin)

Related

• Policy Model
• Nodes
• Framework Integrations