> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valmi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Keys & Mapping

> Understanding agent keys and how to use them

## 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](https://cloud.valmi.io)
2. Navigate to **Agents** → Select an agent → **Instances**
3. Create or select an instance
4. Copy the **Agent Key**

<Warning>
  Agent keys are secret credentials. Keep them secure and never commit them to version control.
</Warning>

## Using Agent Keys

Use the agent key in SDK calls:

```python theme={null}
value.send_action(
    agent_key="agent_abc123xyz",  # Your agent key
    action_type="llm_call",
    metadata={...}
)
```

## Environment-Based Keys

Use different keys for different environments:

```python theme={null}
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

<Info>
  There's a 24-hour grace period where both old and new keys work, giving you time to update your code.
</Info>

## Multiple Instances

Use different keys for different instances:

```python theme={null}
# 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