Agents

Agents are governed identities for your AI systems. Each agent gets a unique cryptographic identity with ML-DSA signatures, enabling audit trails, access control, and compliance tracking.

Creating Agents

Create an agent with a unique name:

python 
import asqav

# Initialize with your API key
asqav.init(api_key="sk_...")

# Create an agent
agent = asqav.Agent.create("my-agent")

print(f"Agent ID: {agent.agent_id}")
print(f"Name: {agent.name}")
print(f"Algorithm: {agent.algorithm}")
print(f"Created: {agent.created_at}")
typescript 
import { init, Agent } from "@asqav/sdk";

// Initialize with your API key
init({ apiKey: "sk_..." });

// Create an agent
const agent = await Agent.create({ name: "my-agent" });

console.log(`Agent ID: ${agent.agentId}`);
console.log(`Name: ${agent.name}`);
console.log(`Algorithm: ${agent.algorithm}`);
console.log(`Created: ${agent.createdAt}`);

Algorithm Selection

Multiple ML-DSA security levels are supported:

Algorithm Security Level Signature Size Tier
ml-dsa-44 NIST Level 2 2,420 bytes Free
ml-dsa-65 NIST Level 3 3,309 bytes Free (default)
ml-dsa-87 NIST Level 5 4,627 bytes All plans
python 
# Create with specific algorithm
agent = asqav.Agent.create(
    name="high-security-agent",
    algorithm="ml-dsa-87"
)

Retrieving Agents

python 
# Get agent by ID
agent = asqav.Agent.get("agent_abc123")

# List all agents
agents = asqav.Agent.list()
for agent in agents:
    print(f"{agent.name}: {agent.status}")

Agent Status

Agents can be in the following states:

Status Description
active Agent can sign and issue tokens
suspended Agent is temporarily blocked. Can be unsuspended
revoked Agent is disabled, signatures rejected

Lifecycle actions (suspend, revoke, decommission) are available on all tiers.

Revoking Agents

Revoke an agent to immediately invalidate all its tokens and reject future signatures:

python 
# Revoke with a reason
agent.revoke(reason="suspicious_activity")

# Check revocation status
if agent.status == "revoked":
    print(f"Revoked at: {agent.revoked_at}")
    print(f"Reason: {agent.revocation_reason}")
Tip

Third parties can verify revocation status via OCSP on all tiers, without needing your API key.

Signing Actions

Create cryptographic signatures for any action:

python 
# Simple action signing
signature = agent.sign("api:openai:chat")

# With context
signature = agent.sign(
    "database:query",
    {
        "table": "users",
        "operation": "select",
        "count": 100
    }
)

# Signature contains
print(f"Signature: {signature.signature}")
print(f"Timestamp: {signature.timestamp}")
print(f"Action ID: {signature.action_id}")

Output Verification

Bind a signed record to both its input and output so you can later prove the output has not been modified since generation. Use sign_output to store an input/output hash pair, then verify_output to check a candidate output against the signed hash.

python 
import hashlib
import asqav

question = "What is the capital of France?"
answer = {"answer": "Paris"}

input_hash = hashlib.sha256(question.encode()).hexdigest()

# Sign the output, bound to the input hash
sig = agent.sign_output(
    action_type="tool:search",
    input_hash=input_hash,
    output=answer,
)

# Later, verify the output is authentic and unmodified
result = Asqav.verify_output(sig.signature_id, answer)
if result["verified"]:
    print("Output is authentic and unmodified")
Why it matters

Output hash binding detects tampering between generation and consumption, useful for RAG, tool results, and anything you want to replay with proof.

Pre-flight Checks

Run a single check that combines agent status (revoked, suspended) and organization policies before executing a sensitive action. Fails open on transient errors so a flaky check never blocks a healthy agent.

python 
check = agent.preflight("data:read")

if not check.cleared:
    print("Blocked:", check.reasons)
    raise RuntimeError("agent not cleared for action")

# check.cleared, check.agent_active, check.policy_allowed, check.reasons
agent.sign("data:read")

Portable Attestations

Export a portable trust signal that proves an agent's governance status to third parties. The attestation embeds the agent's public key, a signed action summary, and a content hash so any recipient can verify it without access to your API key.

python 
import asqav

# Generate an attestation, optionally scoped to a session
attestation = Asqav.generate_attestation(
    agent_id=agent.agent_id,
    session_id="sess_xyz",
)

print(attestation["attestation_hash"])
print(attestation["public_key"])

# Any recipient can verify it
result = Asqav.verify_attestation(attestation)
if result["valid"] and result["all_valid"]:
    print(f"Verified {result['signatures_checked']} signatures")

Budget Tracking

Track client-side spend for an agent with a tamper-evident trail. Each recorded cost is signed via the agent, so the full spend history can be independently replayed. The tracker fails closed: a cost that would exceed the limit is denied before the action runs.

python 
import asqav

agent = asqav.Agent.create("my-agent")
budget = Asqav.BudgetTracker(agent, limit=10.0, currency="USD")

# Pre-check before spending
decision = budget.check(estimated_cost=0.25)
if not decision.allowed:
    raise RuntimeError(decision.reason)  # "budget_exhausted"

# ... perform the action ...

# Record actual cost with a signed audit entry
budget.record(
    action_type="api:openai",
    actual_cost=0.23,
    context={"model": "gpt-4"},
)

print(budget.status())
# {"limit": 10.0, "currency": "USD", "spend": 0.23, "remaining": 9.77, ...}

Best Practices

Not sure where to start?

Use the Setup Wizard to configure your agent governance strategy, or take the readiness assessment to evaluate your current posture.

Drive the same operations from the terminal with asqav agents (list, create, revoke).