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 — update the 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 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

ScenarioRecommended Method
Running agents in the terminalCLI or Agent Skill
Custom TypeScript/JS agentNode SDK
Python agent or notebookPython SDK
LangChain / CrewAI frameworkPython SDK + integration
CI/CD pipelineCLI
Non-JS/Python languageREST API
Zapier / n8n / MakeREST API

Next Steps