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

A custom integration can use a running timer, or record a completed duration. A timer-based integration makes each action explicit:

  1. Start — create a time entry when the agent begins work.
  2. Stop — stop the running time entry when the agent finishes.
  3. Record cost when needed — explicitly create an expense using a known amount or configured category rate. Token metadata alone does not establish a price.

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

Keep the ID of a timer your integration created and stop it explicitly when work finishes or fails. Do not delete failed work automatically: your application should decide whether the time should be retained, corrected or discarded. The Python SDK does not provide a built-in tracking context manager or implicit cleanup.

For concurrent workers, record completed durations instead of replacing a user’s single active timer. Node and Python show explicit application-owned helpers. Custom SDK examples use source: "api"; automatic Agent Skill lifecycle capture has its own validated metadata contract.

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 with your own explicit wrapper
CI/CD pipeline CLI
Non-JS/Python language REST API
Zapier / n8n / Make REST API
Asking Claude Desktop, ChatGPT, or Grok to track time, review billing or project archives, or draft an invoice Hosted MCP connector

Chat connectors and automatic capture are different things. The Claude Desktop and ChatGPT MCP connectors act only when you ask the assistant to call a Keito tool in a conversation, and they return authorised data to the assistant you chose. They can review active projects for archiving, but require your approval of the exact projects and warnings before an archive. A manager or admin with invoice access can also ask the assistant to review billing, or draft an invoice and send it after confirming the exact total. Automatic session capture, with the Agent Skill or CLI agent mode, records agent work as it runs without a chat.

Next Steps