Agent Definition DSL¶

Agent definitions let you publish new AI capabilities through configuration-as-code. While agent manifests (config/kiket/agents/*.yml) control how first-party agents are exposed inside the product, definition files describe the reusable blueprint that lives in your repositories – including inputs, outputs, prompts, and tool wiring.

Where to store definitions¶

Place YAML files under one of the configuration roots that Kiket watches during a sync:

agents/
├── triage_coach.yaml
├── executive_digest.yaml
└── onboarding_companion.yaml

You can commit the folder to:

definitions/<template>/agents/*.yaml – shared starter templates.
storage/workflow_sources/organizations/<slug>/agents/*.yaml – organisation libraries.
storage/workflow_sources/projects/<slug>/agents/*.yaml – project-level overrides.
Optional .kiket/agents/*.yaml within any of these roots (avoid mixing them with manifest files in repositories cloned directly by the Rails app).

Every file must declare model_version: "1.0" at the top level.

Schema overview¶

Key	Type	Required	Notes
`model_version`	String	✅	Currently `1.0`.
`agent.id`	String	✅	Lowercase slug (`a-z`, `0-9`, `_`, `-`, `.`).
`agent.name`	String	✅	Human-friendly label shown in tooling.
`agent.description`	String	➖	Short synopsis for docs and galleries.
`agent.capabilities`	Array\<String>	✅	Capability tags such as `triage`, `summarize`, `assign`.
`agent.inputs`	Array\<Input>	➖	Structured inputs required by the agent.
`agent.outputs`	Array\<Output>	➖	Structured outputs produced by the agent.
`agent.prompts`	Array\<Prompt>	➖	Prompt messages (role/content).
`agent.tools`	Array\<Tool>	➖	Tool declarations available to the agent runtime.

Inputs & outputs¶

Each entry is a hash. Strings are accepted as shorthand and normalised to { "name" => "value", "type" => "string" }.

Key	Required	Default	Example
`name`	✅	–	`incident`, `history`
`type`	➖	`string`	`Issue`, `Collection<Issue>`, `Markdown`
`description`	➖	–	Display hints for UI tooling

Prompts¶

Prompt entries support both formats:

String: treated as a system message.
Hash: { role: "system" | "user" | "assistant", content: "..." }

Tools¶

Tool entries expose external calls the agent can make (for example, a webhook). Structure:

Key	Required	Notes
`id`	✅	Unique identifier within the agent definition.
`type`	➖	Defaults to `http`.
`config`	➖	Free-form data interpreted by the runtime or integration.

Example¶

model_version: "1.0"
agent:
  id: triage.coach
  name: Triage Coach
  description: Helps sort incoming incidents and propose next steps.
  capabilities:
    - triage
    - summarize
  inputs:
    - name: incident
      type: Issue
      description: Incident payload to analyse.
    - name: history
      type: Collection<Issue>
  outputs:
    - name: plan
      type: Markdown
      description: Step-by-step mitigation guidance.
  prompts:
    - role: system
      content: |
        You are an incident coach. Produce a short summary and actionable next steps.
    - role: user
      content: "<%= incident.description %>"
  tools:
    - id: escalate_http
      type: http
      config:
        url: https://hooks.example.com/escalate
        method: POST

How definitions are loaded¶

During a sync, ConfigurationLoader parses every file via KiketScript::AgentParser. The normalised result (including source path and model version) is stored under project.settings["agents"]. Downstream services and UI layers can then discover the available agents for the current project without touching the repository directly.

If parsing fails, the loader records an error message and leaves existing definitions untouched, so production projects are never overwritten with invalid YAML.

Best practices¶

Version-control definitions and prompt templates together.
Use strong type hints (Issue, Markdown) to help UI tooling render forms and previews.
Keep capability tags short and verb-based.
Avoid embedding credentials in definitions—reference secrets from tool configuration instead.
Validate changes by running your usual configuration sync (admin UI or kiket sync) before promoting to production.