Apps, actions and skills

What lets “press 1 to book” and “I’d like to book” reach the same code, and what decides which of those a virtual agent may do.

Three words, and the middle one is the one that matters.

App	a capability with a life outside the call: a table, a screen, permissions. Tickets, satisfaction. Switched on per organisation
Action	one operation an app performs, described once: a name, the arguments it takes, the outcomes it can have
Skill	an action offered to a virtual agent, as a tool it may choose to use

An action has two callers: a model deciding mid-conversation, and an IVR flow node the designer wired. “Press 1 to book an appointment” and “I’d like to book an appointment” must reach the same code, or the two paths drift and one of them is wrong.

That is the whole reason action and skill are separate ideas. The action is described once; the skill is that description handed to a model.

What an action carries

• A name, unique across every app, because it is also what a model sees.
• One sentence of description, shown to the model and in the flow designer’s node palette. Both readers are deciding whether this is the thing they want.
• The arguments it takes, as a schema. One schema, three consumers: the model’s tool definition, the designer’s form for the node, and the check on the server. The form therefore cannot drift from what the handler actually accepts.
• Its outcomes, which become the flow node’s outlets and the results a model is told about. Every action has at least ok and error.

Some actions are agent-only — they need a live conversation, such as summarising what a caller said. They are not offered in the node palette, because a flow drawn with one could not run.

What a virtual agent may actually do

The set offered to an agent is an intersection, and both halves are needed:

1. the apps switched on for the organisation, and
2. the skills listed on that profile.

An app that is off contributes nothing even where a profile lists its skills — otherwise switching an app off would leave agents still calling into it. And a skill the profile does not list is not offered even where the app is on, because two agents in one organisation should differ: a front desk books appointments and transfers, an after-hours agent takes a message and nothing else.

The check is made again when the action runs, not trusted from when the tool list was built. A call can outlive a settings change, and a model told about an action at the start of a call will happily use it ten minutes after the app was switched off.

A flow node is filtered only by which apps are on, never by a profile. A flow node is not an agent, and the designer placing one is the decision.

What exists today

Action
transfer_to_human	hand the call to a person
end_call	finish the conversation
request_callback	promise a call back, and raise the ticket for it
search_knowledge	look something up in the knowledge base
identify_customer	attach the caller to a customer record
remember, learn	keep something the caller said
conference_add	bring somebody else onto the call
ticket_create, ticket_lookup, ticket_update	the tickets app
collect_csat	ask for a rating, spoken or by keypad

The first set are core: things done to the call itself. A transfer is not a record, it is an event, and it is over the moment it happens, so it has no app, no table and no screen. The rest belong to an app and appear only where that app is on.

Arguments are checked before anything runs

Arguments from a model are model output, and an unchecked one reaches a database or the switch. They are validated against the action’s own schema first: the required fields, their types, any list of allowed values, and any upper and lower bound.

A bound the schema states must be a bound the check keeps. This was once not true — the rating action declared 1 to 5, a score of 99 passed validation, and the handler quietly discarded it, so a model’s mistake looked like a caller who would not answer. A schema that states a rule and does not hold it is worse than one that states nothing.