Skip to main content

​
Sending Actions

Send action events to meter agent usage: 
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: 
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

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

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: 
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: 
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: 
await value.send_action(
    agent_key="agent_abc123xyz",
    action_type="llm_call",
    metadata={...}
)

​
Error Handling

Handle errors gracefully: 
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}")
Events are automatically buffered locally if the API is unavailable. They’ll be sent when the connection is restored.