Use cases - Komodor

An agent can do more than answer a prompt. A use case is a named, schema-typed action the agent advertises — triage a build, run a backup — and the Komodor Agentic Operation Platform (KAOP) turns each one into a callable tool on that agent’s own endpoint. This page covers what a use case is, how it differs from two things it is easily confused with, how you declare one, and the two every agent gets for free.

It is not a skill, and not a capability flag

These three sit close together and do different jobs. Mixing them up is the usual mistake.

	What it is	Who reads it
Use case	An invocable, schema-typed action with its own input and output	Something calling the agent from outside
Skill	An instruction document — a runbook or procedure	The agent itself, while it works
Capability flag	A boolean on the agent card (`chat`, `review`, `grader`) saying what class of work the agent accepts at all	The platform, when it routes work

A skill shapes how the agent works. A capability says what class of work it takes. A use case is an entry point someone else can call.

Declaring one

Use cases live in the worker’s agent-spec.yaml, and the agent advertises them itself — there is nothing to register separately.

use_cases:
  - slug: triage_build
    description: Triage a failed CI build and summarize the likely cause.
    input_schema:
      type: object
      properties:
        build_id: { type: string }
      required: [build_id]
    output_schema:
      type: object
      properties:
        cause: { type: string }
    timeout_seconds: 300
  - slug: run_backup
    description: Run an on-demand backup.
    timeout_seconds: 120

Field	Required	What it means
`slug`	yes	The stable identifier, and the tool name. Lowercase letters, digits, `_` or `-`; starts and ends alphanumeric; 64 characters or fewer; unique within the agent.
`description`	yes	Becomes the tool’s description, read by both people and models. Write it as an instruction, not a label.
`input_schema`	no	JSON Schema for the input. Leave it out and the use case takes free text.
`output_schema`	no	JSON Schema for the result. Leave it out and the result is free text.
`timeout_seconds`	yes	1–3600. How long a blocking call waits for the worker to get a slot and finish. Keep it below any load-balancer idle timeout in front of the caller.

A malformed spec is rejected when you author it rather than at run time, and the same definition is the wire format — there is no second place for it to drift.

Use cases travel inside the agent card, so changing them registers as a new generation of the agent. There is nothing separate to publish.

Every agent already has two

Both are advertised automatically, so a freshly deployed agent always has a safe command you can run to prove it works.

Use case	What it proves
Check connectivity	A canned, deterministic reply with no model, no tools, no integrations — it short-circuits before your handler runs, so it always succeeds. It proves the platform can reach the worker and that runs and transcripts are flowing. This is what the one-click check runs.
Sample run	A real run through your actual handler and model, with a canonical self-introduction prompt, producing a live transcript. It proves the whole path including the model.

Declaring your own connectivity_check or sample_run keeps your definition instead.

When a newly deployed agent looks wrong, run these in order. Check connectivity failing points at deployment or networking; Check connectivity passing while Sample run fails points at the model, the tools, or the handler.

Calling one

Every agent is served as its own MCP server, so a client can connect to that one agent:

{
  "mcpServers": {
    "buildkite-triage": {
      "url": "https://<control-plane>/agent-mcp/buildkite-triage/mcp",
      "headers": { "Authorization": "Bearer <AGENTOPS_API_KEY>" }
    }
  }
}

Alongside your declared use cases, every agent exposes two universal tools:

invoke — starts a run. It is typed from the agent’s own input schema when it has one, and otherwise takes free text. It also accepts a use_case field, so calling invoke with use_case: "triage_build" reaches exactly the same path as calling triage_build directly.
get_run — checks a run that invoke started. Given a run id it reads the current state; give it a wait and it blocks for up to 45 seconds instead of returning immediately.

Declared use cases are additive: a typed agent keeps its own tools and gets these two. The agent’s Metadata tab carries the connection details for this endpoint — the URL, a ready-made client command, and the use cases it publishes.

Next steps

Build from scratch

Where agent-spec.yaml lives, and the rest of what it declares.

Skills

The know-how an agent reads, as opposed to an entry point it offers.

MCP server

The platform’s own MCP surface, distinct from an agent’s.

Deploy an agent

Getting to the point where there is something to call.

​It is not a skill, and not a capability flag

​Declaring one

​Every agent already has two

​Calling one

​Next steps

Build from scratch

Skills

MCP server

Deploy an agent

It is not a skill, and not a capability flag

Declaring one

Every agent already has two

Calling one

Next steps