> ## 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.

# Sending Meter Events

> Sending actions and outcomes from your agents

## Sending Actions

Send action events to meter agent usage:

```python theme={null}
value.send_action(
    agent_key="agent_abc123xyz",
    action_type="llm_call",
    metadata={
        "model": "gpt-4",
        "input_tokens": 1000,
        "output_tokens": 500,
        "cost_usd": 0.06,
        "latency_ms": 1250
    }
)
```

### Action Parameters

* **agent\_key** (required): The agent instance key
* **action\_type** (required): Type of action (e.g., "llm\_call", "tool\_call")
* **metadata** (optional): Key-value pairs with action details
* **timestamp** (optional): Event timestamp (defaults to now)

### Common Action Types

* `llm_call` - LLM API invocation
* `embedding` - Vector embedding generation
* `tool_call` - External tool or API call
* `agent_execution` - Complete agent run
* `workflow_step` - Step in a workflow
* `custom` - Custom action type

## Sending Outcomes

Send outcome events for business results:

```python theme={null}
value.send_outcome(
    agent_key="agent_abc123xyz",
    outcome_type="successful_hire",
    value=1,
    metadata={
        "candidate_id": "cand_123",
        "position": "Software Engineer",
        "salary": 120000
    }
)
```

### Outcome Parameters

* **agent\_key** (required): The agent instance key
* **outcome\_type** (required): Type of outcome (e.g., "successful\_hire")
* **value** (required): Outcome value (count or amount)
* **metadata** (optional): Additional context
* **timestamp** (optional): Event timestamp (defaults to now)

## Attaching Metadata

Metadata provides context about events:

### LLM Call Metadata

```python theme={null}
value.send_action(
    agent_key="agent_abc123xyz",
    action_type="llm_call",
    metadata={
        "model": "gpt-4",
        "provider": "openai",
        "input_tokens": 1000,
        "output_tokens": 500,
        "temperature": 0.7,
        "max_tokens": 2000,
        "cost_usd": 0.06,
        "latency_ms": 1250
    }
)
```

### Tool Call Metadata

```python theme={null}
value.send_action(
    agent_key="agent_abc123xyz",
    action_type="tool_call",
    metadata={
        "tool_name": "stripe_api",
        "endpoint": "create_payment",
        "cost_usd": 0.05,
        "success": True
    }
)
```

### Custom Metadata

Add any custom fields:

```python theme={null}
value.send_action(
    agent_key="agent_abc123xyz",
    action_type="custom_action",
    metadata={
        "customer_id": "cust_123",
        "workflow_id": "wf_456",
        "custom_field": "custom_value",
        "any_data": {"nested": "structure"}
    }
)
```

## Batch Sending

Send multiple events efficiently:

```python theme={null}
actions = [
    {
        "agent_key": "agent_abc123xyz",
        "action_type": "llm_call",
        "metadata": {...}
    },
    {
        "agent_key": "agent_abc123xyz",
        "action_type": "tool_call",
        "metadata": {...}
    }
]

value.send_actions(actions)
```

## Async Sending

For async applications:

```python theme={null}
await value.send_action(
    agent_key="agent_abc123xyz",
    action_type="llm_call",
    metadata={...}
)
```

## Error Handling

Handle errors gracefully:

```python theme={null}
try:
    value.send_action(
        agent_key="agent_abc123xyz",
        action_type="llm_call",
        metadata={...}
    )
except ValueError as e:
    # Invalid parameters
    print(f"Invalid action: {e}")
except ConnectionError as e:
    # Network error - event is buffered locally
    print(f"Connection error: {e}")
except Exception as e:
    # Other errors
    print(f"Error: {e}")
```

<Info>
  Events are automatically buffered locally if the API is unavailable. They'll be sent when the connection is restored.
</Info>