How to Track and Charge for Your AI Agent's Work

Learn how to see what your AI agents do and bill your customers fairly.

The Real Problem

You built an AI agent. Companies are paying you to use it. But here's the tricky part:

How do you know what to charge them?

Your AI agent does lots of things:

• It talks to ChatGPT or Claude (each call costs you money)
• It searches the internet
• It reads documents
• It sends emails

Every action has a cost. And you need to charge your customers based on what they actually use.

Think of it like a taxi. You don't charge everyone the same price. You charge based on how far they travel. Your AI agent is the same, you charge based on how much work it does.

Valmi Value is like the meter in a taxi. It counts everything your AI does, so you can charge customers fairly and know if you're making money.

What We'll Build

By the end of this guide, you'll have:

1. A way to track every action your AI agent takes
2. A dashboard showing who used what
3. The data you need to bill customers based on actual usage

Before You Start

You'll need:

• Python 3.9 or newer
• Basic Python knowledge

Step 1: Sign Up

First, create your Valmi Value account at value.valmi.io.

This is where you'll manage your agents, customers, and billing.

Step 2: Create a Customer Account

In business, you have customers. Each customer needs an account so you can track their usage separately.

Think of it like a gym. Each member has their own card. When they scan in, you know who's using the equipment and how much.

To create an account:

1. Log into value.valmi.io
2. Click Accounts in the sidebar
3. Click Create Account
4. Enter your customer's details:
   • Name: Acme Corp
   • Email: billing@acme.com
   • Phone: +1-555-123-4567
   • Address: 123 Main Street, San Francisco, CA 94102
   • Description: Enterprise customer - AI research tools
5. Click Create

Now Acme Corp has their own account. Any AI work they do gets tracked separately from your other customers.

Step 3: Add a Contact

Every customer account needs a person you can reach. This is who gets invoices and usage alerts.

1. Open the account you just made
2. Click Contacts tab
3. Click Add Contact
4. Fill in:
   • Name: John Doe
   • Email: john@acme.com
   • Phone: +1-555-987-6543
   • Address: 123 Main Street, San Francisco, CA 94102
   • Description: Primary billing contact for AI services
5. Click Add

Now when you send Acme Corp their bill, John gets the email.

Step 4: Create an Agent Type

You might build different AI agents for different jobs:

• A customer support agent
• A research agent
• A data analysis agent

Each type is like a different product you sell. Let's create one.

1. Click Agents in the sidebar
2. Click Agent Types tab
3. Click Create Agent Type
4. Fill in:
   • Name: Research Agent
   • Description: Researches topics and summarizes findings
   • Type: Custom Agent (or choose LangGraph, CrewAI, etc.)
5. Click Create

This is like adding a new product to your catalog.

Step 5: Create an Agent Instance

An Agent Type is like a blueprint. An Agent Instance is an actual working copy.

Why does this matter? Because different customers might use the same type of agent, but you want to track them separately.

Think of it like a rental car company. "Toyota Camry" is the type. But each actual car has its own license plate so you know which customer has which car.

1. Click Agents → Instances in the sidebar
2. Click Create Instance
3. Fill in:
   • Name: Acme Research Agent
   • Description: Research agent instance for Acme Corp
   • Agent Type: Select Research Agent
   • Account: Select Acme Corp
   • Contact: Select John Doe
4. Click Create
5. Copy the Agent Secret — this is the key that identifies this specific agent

Important: The Agent Secret is like a password. Keep it safe. Don't put it directly in your code where others can see it.

Step 8: Track Actions

Now the important part. Every time your agent does something billable, you record it.

Here's a real example: a research agent that:

1. Searches for information
2. Calls an LLM to summarize
3. Sends results to the user

import os
from value import initialize_sync

AGENT_SECRET = os.getenv("VALUE_AGENT_SECRET")
client = initialize_sync(agent_secret=AGENT_SECRET)

def run_research(user_id: str, topic: str):
    """
    A research agent workflow.
    Each action is tracked so we know what to charge.
    """

    # action_context ties all actions to a specific user
    with client.action_context(user_id=user_id) as ctx:

        # ACTION 1: Web search
        # In real code, this would call a search API
        search_results = perform_web_search(topic)

        ctx.send(
            action_name="web_search",
            **{
                "value.action.description": f"Searched for: {topic}",
                "results_count": len(search_results),
                "search_provider": "google",
            }
        )

        # ACTION 2: LLM summarization
        # This costs money - track the tokens
        summary = call_llm_to_summarize(search_results)

        ctx.send(
            action_name="llm_call",
            **{
                "value.action.description": "Summarized search results",
                "model": "gpt-4",
                "input_tokens": 2500,
                "output_tokens": 800,
                "cost_usd": 0.12,  # Track your actual cost
            }
        )

        # ACTION 3: Deliver results
        send_to_user(user_id, summary)

        ctx.send(
            action_name="delivery",
            **{
                "value.action.description": "Sent summary to user",
                "delivery_method": "email",
            }
        )

        return summary


# Run for a specific customer's user
run_research(user_id="user_acme_123", topic="market trends in AI")

What's happening here:

• action_context(user_id=...) — Groups all actions under one user session
• ctx.send(action_name=...) — Records each action with details
• The metadata (tokens, cost, etc.) helps you understand usage and costs

Step 9: See the Data

Go to value.valmi.io and click Metering → Live Data.

You'll see every action in real-time:

Now you know exactly:

• Which customer used your agent
• What actions were performed
• How much each action cost you
• Data to build usage-based billing

Step 10: Auto-Track LLM Calls (Optional)

Manually tracking every LLM call is tedious. If you use Gemini or LangChain, enable auto-instrumentation:

from value import initialize_sync, auto_instrument

client = initialize_sync(agent_secret=AGENT_SECRET)
auto_instrument(["gemini"])  # Automatically tracks all Gemini calls

# Now just use Gemini normally — all calls are tracked automatically
from google import genai

gemini = genai.Client(api_key="your-key")
response = gemini.models.generate_content(
    model="gemini-2.5-flash",
    contents=["Analyze this market data..."]
)

Every LLM call is recorded with model name, tokens, and latency — no extra code needed.

The Business Value

With all this tracking data, you can now:

1. Bill Based on Usage

Charge customers for what they actually use. "You made 500 LLM calls this month at $0.002 each = $1.00"

2. Know Your Margins

You can see: "This customer paid us $100, but their LLM costs were $80. Our margin is only 20%."

3. Find Heavy Users

See which customers use the most resources. Maybe they need a higher plan.

4. Optimize Costs

Find which actions cost the most. Maybe switch to a cheaper model for simple tasks.

Best Practices

Name Actions Clearly

# Good — describes what happened
ctx.send(action_name="document_parsed")
ctx.send(action_name="customer_query_answered")

# Bad — meaningless
ctx.send(action_name="step_1")
ctx.send(action_name="done")

Track What Matters for Billing

ctx.send(
    action_name="llm_call",
    **{
        "model": "gpt-4",           # Which model (affects cost)
        "input_tokens": 1500,        # Input size
        "output_tokens": 500,        # Output size
        "cost_usd": 0.045,          # Your actual cost
        "latency_ms": 1200,         # Performance tracking
    }
)

Always Identify the User

# Known customer user
with client.action_context(user_id="customer_123") as ctx:
    ...

# Anonymous/trial user
with client.action_context(anonymous_id="trial_session_abc") as ctx:
    ...

Keep Secrets Safe

Never hardcode secrets. Use environment variables:

export VALUE_AGENT_SECRET="your-secret"

import os
secret = os.environ["VALUE_AGENT_SECRET"]

What's Next?

Now that you're tracking actions, you can:

1. Define Outcomes: Group actions into billable outcomes like "research completed"
2. Set Up Pricing: Create pricing rules (per action, tiered, etc.)
3. Allocate Costs: Attribute LLM costs to understand margins
4. Generate Invoices: Bill customers based on actual usage

Summary

You learned how to:

• Create customer accounts to track usage separately
• Set up agent types and instances
• Track every action your AI agent takes
• View real-time usage data
• Enable automatic LLM tracking

This gives you the foundation for usage-based billing — charge customers fairly based on what they actually use, and know exactly what it costs you to serve them.

Resources

• Documentation
• Python SDK on PyPI
• GitHub

Questions? Reach out at contact@valmi.io