Skip to main content

​
What are Agent Keys?

An Agent Key is a unique identifier for an agent instance. It’s used in SDK calls to identify which agent instance is sending events.

​
Getting Your Agent Key

  1. Log in to the Valmi Value Control Plane
  2. Navigate to Agents → Select an agent → Instances
  3. Create or select an instance
  4. Copy the Agent Key
Agent keys are secret credentials. Keep them secure and never commit them to version control.

​
Using Agent Keys

Use the agent key in SDK calls: 
value.send_action(
    agent_key="agent_abc123xyz",  # Your agent key
    action_type="llm_call",
    metadata={...}
)

​
Environment-Based Keys

Use different keys for different environments: 
import os

# Get key from environment
agent_key = os.getenv("VALMI_AGENT_KEY", "agent_abc123xyz")

value.send_action(
    agent_key=agent_key,
    action_type="llm_call",
    metadata={...}
)

​
Key Mapping

The Control Plane maps agent keys to:
  • Agent Instance: Which instance the key belongs to
  • Pricing Rules: Instance-specific pricing
  • Cost Allocation: How costs are attributed
  • Subscriptions: Which customer subscription (if any)

​
Key Rotation

Periodically rotate agent keys for security:
  1. In the Control Plane, navigate to the instance
  2. Click Rotate Key
  3. New key is generated
  4. Old key is invalidated (with 24-hour grace period)
  5. Update your code with the new key
There’s a 24-hour grace period where both old and new keys work, giving you time to update your code.

​
Multiple Instances

Use different keys for different instances: 
# Production instance
value.send_action(
    agent_key="agent_prod_abc123",
    action_type="llm_call",
    metadata={...}
)

# Staging instance
value.send_action(
    agent_key="agent_staging_xyz789",
    action_type="llm_call",
    metadata={...}
)

​
Key Validation

The SDK validates agent keys:
  • Format Check: Validates key format
  • Existence Check: Verifies key exists (on first use)
  • Status Check: Ensures key is active
Invalid keys will result in errors when sending events.

​
Best Practices

  • Store Securely: Use environment variables or secret management
  • Rotate Regularly: Rotate keys every 90 days
  • Use Different Keys: Separate keys for different environments
  • Monitor Usage: Track key usage in the Control Plane