Agent Integration Overview

This section explains the concepts behind agent tracking in Keito and provides guidance for integrating any AI agent — whether you’re using the SDK, CLI, or building a custom integration.

The Core Pattern

Every agent integration follows the same three-step pattern:

Start — create a time entry when the agent begins work.
Stop — update the time entry when the agent finishes.
Log cost — create an LLM expense for token usage.

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Start Timer │────▶│  Agent Works │────▶│  Stop Timer  │
│  POST entry  │     │   ...        │     │  PATCH entry │
│  is_running: │     │              │     │  hours: 1.5  │
│  true        │     │              │     │  is_running: │
│              │     │              │     │  false       │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                           ┌──────▼───────┐
                                           │  Log Expense │
                                           │  POST expense│
                                           │  units: 45   │
                                           └──────────────┘

Session Correlation

Use a shared session_id in the metadata of both the time entry and the expense to link them:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "review-bot-01"
}

This lets you trace which token costs correspond to which work sessions in reports.

Error Handling

If the agent fails mid-session:

CLI: keito time stop --discard
SDK: Delete the time entry (keito.timeEntries.delete(entry.id))
Python context manager: Automatic — discards on exception.

Don’t leave running timers from failed sessions. They’ll appear as in-progress entries in the UI.

Choosing an Integration Method

Scenario	Recommended Method
Running agents in the terminal	CLI
Custom TypeScript/JS agent	Node SDK
Python agent or notebook	Python SDK
LangChain / CrewAI framework	Python SDK + integration
CI/CD pipeline	CLI
Non-JS/Python language	REST API
Zapier / n8n / Make	REST API

Next Steps

How Agent Billing Works — rates, margins, and invoicing
Quickstart — create your first agent time entry
Node SDK Agent Integration — TypeScript patterns
Python SDK Agent Integration — Python patterns