Binding¶

This page lists every field of the Binding resource, as the Go types in api/v1alpha1 define it. You do not set status: it is the observed state, described in Binding status.

The Default column shows what happens when a field is omitted. None means no default is supplied.

apiVersion: agentkourier.dev/v1alpha1 · kind: Binding

Binding connects one agent to one chat channel. Owned by an application team.

Binding¶

Field	Type	Required	Default	Description
`metadata`	ObjectMeta	Yes	None	Standard Kubernetes object metadata. Agent Kourier reads `name` and `namespace`.
`spec`	BindingSpec	Yes	None
`status`	BindingStatus	No	None	Status is the observed state of the Binding. It is set through the status subresource and never in a file: the file loader refuses a Binding file that sets it.

BindingSpec¶

BindingSpec is the desired state of a Binding.

Field	Type	Required	Default
`agent`	AgentRef	Yes	None
`identity`	Identity	Yes	None
`chat`	ChatBinding	Yes	None
`interactions`	Interactions	No	None
`feedback`	Feedback	No	None
`session`	Session	No	None

AgentRef¶

AgentRef names the agent on a backend.

Field	Type	Required	Default	Description
`backendRef`	ObjectRef	Yes	None
`name`	string	Yes	None	Name is the agent's name on the backend, at most 253 bytes. At least 1 character. At most 253 characters.
`namespace`	string	Yes	None	Namespace is the agent's namespace on the backend: a DNS-1123 label of at most 63 lowercase letters, digits or '-', starting and ending with a letter or digit. Pattern `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`. At most 63 characters.

ObjectRef¶

ObjectRef names a resource in a namespace. An empty namespace means the namespace of the referring object. A Binding's agent.backendRef and chat.connectionRef may name an AgentBackend or a ChatConnection in another namespace only if that resource lists the Binding's namespace in its allowedNamespaces.

Field	Type	Required	Default	Description
`namespace`	string	No	Namespace of the referring object	Namespace is a DNS-1123 label: at most 63 lowercase letters, digits or '-', starting and ending with a letter or digit. Pattern `^([a-z0-9]([-a-z0-9]*[a-z0-9])?)?$`. At most 63 characters.
`name`	string	Yes	None	Name is a DNS-1123 subdomain: at most 253 lowercase letters, digits, '-' or '.', starting and ending with a letter or digit. Pattern `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`. At most 253 characters.

Identity¶

Identity is the service identity every turn in the Binding runs as, whoever wrote the message. Set userId, tokenSecretRef, or both.

Field	Type	Required	Default	Description
`userId`	string	No	None	UserID is sent as X-User-Id when the backend runs in insecure mode. At most 256 bytes. At most 256 characters.
`tokenSecretRef`	SecretKeyRef	No	None	TokenSecretRef holds the OIDC bearer token.

SecretKeyRef¶

SecretKeyRef names one value in a Secret in the referring object's namespace.

Field	Type	Required	Default	Description
`name`	string	Yes	None	Name is a DNS-1123 subdomain: at most 253 lowercase letters, digits, '-' or '.', starting and ending with a letter or digit. Pattern `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`. At most 253 characters.
`key`	string	No	`token`	Key selects the entry of the Secret. It defaults to "token". It consists of at most 253 alphanumeric characters, '-', '_' or '.', and is neither "." nor "..", nor does it start with "..". Pattern `^(\.?[-_a-zA-Z0-9][-._a-zA-Z0-9]*)?$`. At most 253 characters.

ChatBinding¶

ChatBinding places the Binding in a channel.

Field	Type	Required	Default	Description
`connectionRef`	ObjectRef	Yes	None
`channel`	string	Yes	None	Channel is the platform's channel ID, not its name (Slack: `C…` or `G…`). At most 32 bytes. Pattern `^[CG][A-Z0-9]+$`. At most 32 characters.
`output`	string	No	`live`	Output defaults to live. One of `live`, `final`.
`progress`	string	No	`steps-and-activity`	Progress chooses what a live reply shows of the agent's work before its text arrives. steps shows a card for each tool call; an alert thread's first post, which cannot carry cards, shows a status line for the latest call instead, as every write does on a platform without cards. steps-and-activity shows those, and a Working… card (or line, in that first post) whenever 3 seconds pass with nothing new, titled or stood in for by the agent's own progress line. activity shows one Working… card (a line in an alert thread) that counts the steps, or the agent's working updates until the first step is counted, and names no tool, no argument and nothing the agent said. A Binding that sets none gets steps-and-activity. Output final ignores it. One of `steps`, `steps-and-activity`, `activity`.
`threadReplies`	string	No	`all`	ThreadReplies defaults to all: any person's reply in a thread Agent Kourier owns is a turn. With mention, only a reply that mentions Agent Kourier is a turn, whether a mention or a trigger started the thread; the next mentioned turn carries the other replies as context. A typed answer to a pending question that takes text replies needs no mention. One of `all`, `mention`.
`botMentions`	string	No	`any`	BotMentions defaults to any: on a Binding with a mention trigger, a mention of Agent Kourier by any bot or incoming webhook that can post in the channel starts a turn in the mention's thread, with a fixed prompt and held to fixed limits. The platform cannot tell an agent from any other bot. With none, a bot's mention starts nothing. Agent Kourier's own posts, and a bot that a botMessage trigger names, are never taken as a mention. One of `any`, `none`.
`acknowledgment`	ChatAcknowledgment	No	None	Acknowledgment controls the temporary reaction Agent Kourier adds to an accepted message while it is being processed. It defaults to enabled with the platform's own reaction (Slack: hourglass_flowing_sand).
`triggers`	[]Trigger	No	`[{type: mention}]`	Triggers decide which events in the channel start or continue a turn. Empty means [{type: mention}]: a mention starts a session. A list that names triggers is the whole list. At most 50.
`mentions`	[]ChatMention	No	None	Mentions are the people an agent may notify, by writing `@name` in its reply. Agent Kourier then posts a message in the thread that mentions each one named, one message for each. A name not listed here notifies nobody, and an agent can never supply a user ID. Empty means no mentions, and nothing is added to the prompt. At most 50.
`maxMentionsPerTurn`	integer	No	`2`	MaxMentionsPerTurn is the most people one turn mentions, at most 10; the people after them are not mentioned. It defaults to 2. 0 is refused: to notify nobody, leave mentions empty. Minimum 1.

ChatAcknowledgment¶

ChatAcknowledgment configures the temporary reaction on an accepted message.

Field	Type	Required	Default	Description
`enabled`	boolean	No	`true`	Enabled adds the reaction after the message is durably accepted and removes it when processing ends. It defaults to true.
`emoji`	string	No	None	Emoji is the reaction name without colons. Left empty, the platform's own acknowledgment reaction is used (Slack: hourglass_flowing_sand). The API fills in no default, so a stored Binding does not carry one platform's reaction. At most 100 bytes. Pattern `^(?:[a-z0-9][a-z0-9+_-]\|[+-][a-z0-9][a-z0-9+_-])?$`. At most 100 characters.

Trigger¶

Trigger is one way an event in the bound channel starts or continues a turn. Triggers are tried in order and the first that matches handles the event.

Field	Type	Required	Default	Description
`type`	string	Yes	None	Type is mention, a person @mentioning Agent Kourier, or botMessage, a message a bot posts. A mention trigger takes no other field. The key is type, not on: YAML 1.1 reads a bare on as the boolean true, and the loader's decoder follows it. One of `mention`, `botMessage`.
`from`	BotSource	No	None	From names the sender a botMessage trigger accepts. Required for botMessage.
`match`	map[string]string	No	None	Match maps a message field to a regex it must match. Every entry must match. Keys: `text`, `title`, `link`, `fallback`, `footer`, `body`.
`exclude`	map[string]string	No	None	Exclude maps a message field to a regex; a message matching any entry is ignored. Keys: `text`, `title`, `link`, `fallback`, `footer`, `body`.
`extract`	map[string]Extract	No	None	Extract names the values to pull out of a message. A message in which one of these regexes does not match does not match the trigger. At most 32, each named in at most 63 bytes.
`thread`	TriggerThread	No	None	Thread ties messages that share an extracted key to one thread.
`promptTemplate`	string	No	None	PromptTemplate is a Go template over the trigger's view of the message (.Channel, .State, .Key, .Fields, .Link, .Source). Required for botMessage. At most 8192 bytes; it has no loops, variables or defined templates, and calls only and, eq, ge, gt, index, le, len, lt, ne, not, or and slice. At most 8192 characters.
`limits`	TriggerLimits	No	None	Limits bounds how many investigations the trigger starts (rate, concurrency and a daily cap). Required for botMessage: both rateLimit and maxRunsPerDay.

BotSource¶

BotSource identifies the sender whose messages a trigger accepts: a message matches only when its sender's ID and kind both equal ID and Kind.

Field	Type	Required	Default	Description
`id`	string	Yes	None	ID is the sender's ID on the platform, never a display name (Slack: the bot ID, `B…`). The load cannot know Agent Kourier's own ID, so naming it loads: Agent Kourier's own posts are never forwarded, so the trigger matches nothing, and the Slack adapter logs one warning, the first time one of its posts arrives. At most 32 bytes. Pattern `^B[A-Z0-9]+$`. At most 32 characters.
`kind`	string	No	`bot`	Kind is what kind of sender ID names. Only bot exists today, and it is the default. One of `bot`.

Extract¶

Extract pulls one named value out of a message field. The entry's name in Trigger.Extract must also be the name of a named group in Regex, which supplies the value.

Field	Type	Required	Default	Description
`field`	string	Yes	None	Field is the message field the regex runs on. One of `text`, `title`, `link`, `fallback`, `footer`, `body`.
`regex`	string	Yes	None	Regex is a Go (RE2) regular expression of at most 512 bytes. At least 1 character. At most 512 characters.

TriggerThread¶

TriggerThread decides which thread a message joins and when it closes the thread.

Field	Type	Required	Default	Description
`by`	string	No	None	By is key: messages with the same extracted "key" share a thread. One of `key`.
`cooldown`	duration	No	None	Cooldown is how long after a turn the same key starts no new turn. Required with by, and between 1m and 168h. Pattern `^([-+]?0\|[-+]?([0-9]\.?[0-9](ns\|us\|µs\|μs\|ms\|s\|m\|h))+)$`. At most 64 characters.
`maxIdle`	duration	No	Larger of `24h` and twice the cooldown	MaxIdle is how long an open thread may go without a message of its key before Agent Kourier counts it abandoned, so that the key's next fire starts a new investigation instead of a note. It covers a resolve that never arrived. It needs by, is at least twice the cooldown, and is at most 720h; unset means the larger of 24h and twice the cooldown. It must be longer than the sender's repeat interval (Alertmanager's repeat_interval): an alert that keeps firing repeats at that interval, and a maxIdle shorter than it counts a live alert abandoned between two repeats and starts a second investigation for it. Twice the cooldown covers that only for a 4h cooldown against Alertmanager's 4h repeat_interval; a longer repeat_interval needs a maxIdle set above it. Pattern `^([-+]?0\|[-+]?([0-9]\.?[0-9](ns\|us\|µs\|μs\|ms\|s\|m\|h))+)$`. At most 64 characters.
`closeWhen`	map[string]string	No	None	CloseWhen maps an extracted field to the value that closes the thread: Agent Kourier posts a note and starts no turn. Every entry must equal. It names only extracted fields, so it holds at most as many entries as extract does, 32. A value is at most 256 bytes.

TriggerLimits¶

TriggerLimits bounds how many investigations a botMessage trigger starts: a rate limit over a window and a cap for a day. A botMessage trigger sets both. Only a start is limited: a repeat, a close and a note never are.

Field	Type	Required	Default	Description
`rateLimit`	RateLimit	No	None	RateLimit allows MaxRuns starts in any window of Per, and MaxConcurrent investigations running at once. Required for a botMessage trigger, with all three fields set.
`maxRunsPerDay`	integer	No	None	MaxRunsPerDay caps starts in any 24 hours. Required for a botMessage trigger: an explicit 0 means no cap. Minimum 0.

RateLimit¶

RateLimit allows MaxRuns agent runs per window and MaxConcurrent at once.

Field	Type	Required	Default	Description
`maxRuns`	integer	Yes	None	Minimum 1.
`per`	duration	Yes	None	Per is the window length. Pattern `^([-+]?0\|[-+]?([0-9]\.?[0-9](ns\|us\|µs\|μs\|ms\|s\|m\|h))+)$`. At most 64 characters.
`maxConcurrent`	integer	Yes	None	Minimum 1.

ChatMention¶

ChatMention is one person an agent may notify.

Field	Type	Required	Default	Description
`name`	string	Yes	None	Name is what the agent writes, after an `@`: lowercase letters, digits and `-`, starting with a letter, at most 63 characters. `here`, `channel` and `everyone` are refused. Pattern `^[a-z][a-z0-9-]{0,62}$`. At most 63 characters.
`user`	string	Yes	None	User is the platform's user ID of the person (Slack: `U…` or `W…`). It comes only from here, never from the agent. Pattern `^[UW][A-Z0-9]{2,20}$`. At most 21 characters.

Interactions¶

Interactions configures agent pauses that wait on a person.

Field	Type	Required	Default	Description
`askUser`	boolean	No	`false`	AskUser lets the agent ask questions in the thread. Defaults to false.
`toolApprovals`	boolean	No	`false`	ToolApprovals lets the agent ask a person to approve tool calls in the thread. Defaults to false.
`approverGroups`	[]string	No	None	ApproverGroups names the platform's user groups whose members may decide a tool approval, by the platform's ID (Slack: `S…`). An empty list allows any non-bot channel member. At most 10 groups may be named. Group IDs start with S and contain uppercase letters and digits, at most 32 bytes; duplicates and empty entries are refused.
`timeout`	duration	No	`30m`	Timeout is how long a pause waits for an answer. Defaults to 30m. At most 168h (7 days); a longer one is refused. Pattern `^([-+]?0\|[-+]?([0-9]\.?[0-9](ns\|us\|µs\|μs\|ms\|s\|m\|h))+)$`. At most 64 characters.

Feedback¶

Feedback configures the useful and not-useful buttons. The final message of an investigation that a trigger started always carries them; Enabled adds them to the Binding's chat answers too.

Field	Type	Required	Default	Description
`enabled`	boolean	No	`false`	Enabled puts the buttons on the final message of an answer to a person's message in a thread. It does not switch them off for an investigation a trigger started. Defaults to false.

Session¶

Session configures thread-to-session mapping.

Field	Type	Required	Default	Description
`threadTTL`	duration	No	`2160h`	ThreadTTL is how long a thread keeps its session after its last activity. Defaults to 2160h (90 days). At most 8760h (365 days); a longer one is refused. Pattern `^([-+]?0\|[-+]?([0-9]\.?[0-9](ns\|us\|µs\|μs\|ms\|s\|m\|h))+)$`. At most 64 characters.

BindingStatus¶

BindingStatus is the observed state of a Binding.

Field	Type	Required	Default	Description
`conditions`	[]Condition	No	None	Conditions are the Binding's states, one per type. The observedGeneration of a condition is the generation of the Binding it describes.

Generated by hack/docs/refgen from api/v1alpha1. Do not edit this page; change the source and run make docs-ref.