Agent Integration Overview

This section explains the concepts behind agent tracking in Keito and provides guidance for integrating any AI agent, whether you use an SDK, the REST API, or the CLI for terminal-based time tracking.

The Core Pattern

Every agent integration follows the same three-step pattern:

  1. Start — create a time entry when the agent begins work.
  2. Stop — stop the running time entry when the agent finishes.
  3. Log cost — create an LLM expense for token usage.

The CLI covers time tracking and can record completed agent sessions with source=agent and metadata via keito time session-record. Use the API or SDKs when you also need LLM expense logging or tighter integration inside a long-running application process.

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Start Timer │────▶│  Agent Works │────▶│  Stop Timer  │
│  POST entry  │     │   ...        │     │ PATCH /stop  │
│  is_running: │     │              │     │  hours: 1.5  │
│  true        │     │              │     │ calculated by│
│              │     │              │     │ the API      │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                           ┌──────▼───────┐
                                           │  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 or Agent Skill
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