Agents, runs, sessions

Agents, presets & environments

Configurable agents are project-scoped definitions used by:

• Interactive chat (agentDefinitionId on /api/ai/chat)
• Event automations (must name an agent)
• Headless Kubernetes Jobs (development agents with repository / setup / build / test)
• Scheduled tasks targeting AgentRun

Agents — AgentsController (api/agents) — JWT

Method	Path	Auth	Purpose
GET	/api/agents?projectId=	Project member	List (+ automation counts)
GET	/api/agents/{id}	Member	Detail
POST	/api/agents	Member	Create config agent
PUT / DELETE	/api/agents/{id}	Member*	Update / delete (*dev agents with repository: Admin only)
POST	/api/agents/development-template	Admin	Seed K8s dev agent (setup/build/test)
GET / POST / PUT / DELETE	/api/agents/{id}/schedules…	Admin	Legacy agent cron schedules
POST	/api/agents/{id}/runs	Admin	Queue K8s Job (Agents:Enabled or 503)
GET / POST / DELETE	/api/agents/{id}/grants…	Member	Tool grants (not gated on Automations)

Create config agent (automations / chat):

{
  "projectId": 1,
  "name": "Support agent",
  "description": null,
  "providerId": null,
  "systemPrompt": "You are a support agent. Read the customer message and draft a reply.",
  "temperature": 0.2,
  "isActive": true,
  "mcpServerIds": [12],
  "mcpAccountNames": { "12": "default" }
}

Member-facing CRUD cannot author RepositoryUrl, BaseBranch, setup/build/test commands, or budget fields — those are Admin / development-template concerns.

Start run:

{
  "task": "Fix failing tests",
  "idempotencyKey": "manual:abc",
  "deliveryTarget": "PullRequest",
  "gitHubInstallationId": 4287162
}

Tool grant:

{
  "integrationConnectionId": "…",
  "toolName": "pipedream__slack__send_message",
  "externalActionKey": null,
  "actionClass": "ExternalCommunication",
  "allowedResourcePattern": "#support",
  "maxCallsPerRun": 1,
  "requiresApproval": true
}

Environments — AgentEnvironmentsController (api/agent-environments) — Admin

Method	Path	Purpose
GET / POST	/api/agent-environments	List / create profiles
GET / PUT / DELETE	/{id}	CRUD
POST	/ensure-universal	Ensure shared universal profile
GET / POST	/prewarm	Workspace image coverage / prewarm

Profiles override image, storage, CPU, memory, and declared egress hosts.

---

Agent runs (headless Jobs)

Controller: AgentRunsController (api/agent-runs) — Admin (Roles=Admin)

Requires Agents:Enabled + Kubernetes for execution. Runs are queued in PostgreSQL, leased, provisioned as Jobs in namespace agent-runs, and streamed via append-only events.

Method	Path	Purpose
GET	/api/agent-runs?agentId=	List (≤200)
GET	/{id}	Run + artifacts summary
GET	/{id}/events?after=	SSE resumable event stream
POST	/{id}/input	{ "input": "…" } when WaitingForInput
POST	/{id}/cancel	Cancel
POST	/{id}/retry	Retry
GET	/{id}/artifacts	Artifacts
POST	/{id}/memory/{memoryId}/{decision}	Memory review

curl -N "https://your-kroov-host/api/agent-runs/42/events?after=0" \
  -H "Authorization: Bearer $ADMIN_JWT"

---

Interactive sessions

Controller: AgentSessionsController (api/sessions) — JWT (any authenticated user)
Feature bit: agentSessions = AgentSessions:Enabled && Kubernetes:Enabled

Sessions provision a persistent workspace pod (+ PVC). They can clone a GitHub repository or start empty (general-purpose) when both repositoryFullName and repositoryUrl are omitted. projectId remains required (security, billing, provider, MCP boundary).

Method	Path	Purpose
GET / POST	/api/sessions	List / create
GET	/{id}	Detail
GET	/{id}/usage	Lifetime + per-turn usage
POST	/{id}/messages	{ "message": "…" }
POST	/{id}/files	Multipart uploads (files)
POST	/{id}/transcribe	Multipart audio → text (audio)
PATCH	/{id}/settings	provider/model/mode/budgets
POST	/{id}/messages/edit	Edit + rerun from sequence
POST	/{id}/compact	Manual context compaction
POST	/{id}/cancel	Cancel in-flight turn
POST	/{id}/stop	Stop session
DELETE	/{id}	Tear down pod + PVC + history
GET	/{id}/files?path=	Download workspace file (≤25 MB; paths under /workspace/repository or /workspace/uploads)
GET	/{id}/export	ZIP export (≤50 MB, excludes .git)
GET	/{id}/diagnostics	K8s provisioning diagnostics
GET	/{id}/diff / /{id}/changes	Git diff / changed files
GET	/{id}/events?after=	SSE event stream

Create:

{
  "projectId": 1,
  "repositoryFullName": "org/repo",
  "repositoryUrl": "https://github.com/org/repo",
  "branch": "main",
  "gitHubInstallationId": 1,
  "environmentProfileKey": "universal",
  "providerId": 12,
  "model": null,
  "title": "Investigate flake",
  "firstMessage": "Find why CI fails on main"
}

Omit both repository fields for an empty workspace (still requires projectId). Supplying one repository field requires both.

Settings patch:

{
  "providerId": 12,
  "model": "gpt-4o",
  "mode": "Agent",
  "maxInputContextTokens": 128000,
  "maxTokens": 500000,
  "maxEstimatedCostUsd": 25
}

Modes typically include Agent (read/write tools), Plan, and Ask (read-only tool sets).

Usage semantics: lifetime counters are TotalTurns, ActiveMs, TotalModelCalls, TotalToolCalls, InputTokens, OutputTokens. Per-turn guards ModelCalls / ToolCalls reset each turn — do not use them for lifetime reporting.

MCP tools assigned to the project (with the user’s credential/grant) are resolved automatically for interactive sessions.

---