Interactions

An interaction is the thing you actually run. It names the agents taking part, the task they work on, the inputs the task needs, and optionally the tools available, the shape of the answer and the limits on time.

Starting an interaction creates a run with an id. When the run finishes, the answer is in its output.

See it in tutorial 1, Hello, agent, which runs the smallest interaction there is, and tutorial 2, Prompts and inputs, which passes values into the task.

Three kinds

Kind	Folder	Who takes part	Use it for
One-shot	`interactions/one-shot/`	one agent	a question, a task, an extraction: one answer
Round-robin	`interactions/round-robin/`	agents (and optionally a person) taking turns	chats, debates, reviews
Managed	`interactions/managed/`	a manager agent and the team it hands work to	work that splits into parts

Most things start as a one-shot. Round-robin and managed interactions are covered in Teams of agents and, for chatting with a person, in tutorial 7.

A one-shot interaction

agent = {
  name = "Poet"
  agent = @ref("poet")
}
task = @prompt("haiku-task")
inputs.prompts = [
  {
    name = "topic"
    description = "What the haiku is about"
    required = true
  },
  {
    name = "mood"
    description = "Optional mood, for example calm or playful"
    required = false
  }
]

agent is the seat: the name the agent goes by in this interaction, and which agent fills it.

Inputs

Inputs are like function parameters. Declare them under inputs.prompts and use them in the task as %%name%%.

Field	Meaning
`name`	how the task refers to it: `%%topic%%`
`description`	shown in the portal and to callers
`required`	a run without it is refused before it starts, with `api:interactions:input-required`
`type`	`String` (the default), `Integer`, `Decimal` or `Boolean`

Names are case-sensitive. A run that passes an input the interaction doesn’t declare is refused too (api:interactions:input-unknown), and so is a value that isn’t of the input’s type (api:interactions:input-invalid). Nothing is spent on a refused run.

The task can also include text only when an input has a value:

Write a haiku about %%topic%%.
{{#if mood}}
The mood of the haiku should be %%mood%%.
{{/if}}

{{#if mood}} is true when mood has any value at all, so a Boolean input set to false still counts. Use {{#unless name}} for the opposite.

Inputs for tools

Two more kinds of input feed tools instead of the task. The model never sees either, so it can’t change them:

Kind	Declared under	The run’s value
A binding	`inputs.functions.binding`	goes straight into a tool’s calls, as a body field or a query or path parameter: the knowledge base to search, say. See values from the run
A secret	`inputs.functions.auth`	is the id of the secret a tool sends, such as one API key per shop. See secrets chosen by the run

A run passes all three kinds the same way, by name. Unlike a prompt input, a tool input can have a default, which a run that leaves it out uses.

Starting a run

const run = await mt.interactions.run("haiku", { inputs: { topic: "autumn rain", mood: "calm" } });
console.log(run.output);

run = mt.interactions.run("haiku", inputs={"topic": "autumn rain", "mood": "calm"})
print(run.output)

var inputs = new Dictionary<string, string> { ["topic"] = "autumn rain", ["mood"] = "calm" };
var run = await mt.Interactions.RunAsync("haiku", inputs);
Console.WriteLine(run.Output);

mt interaction-run haiku --input-topic "autumn rain" --input-mood calm

curl -X PUT https://api.maitento.com/namespaces/hello-maitento/interactions/by-name/haiku/start \
  -H "Authorization: $MAITENTO_AUTH" -H "Content-Type: application/json" \
  -d '{"inputs": [{"name": "topic", "value": "autumn rain"}, {"name": "mood", "value": "calm"}]}'

The SDKs’ run() starts the run and waits for it. With curl you get the new run straight back, with status New, and fetch it again until it finishes: see Runs and events.

Statuses

Status	Meaning
`New`	accepted, waiting for a worker (or for a free lane: see Limits)
`Running`	working
`HumanInteractionRequired`	waiting for a person to say something. After three days with no message the run is closed as `Finished`; a message sent later opens it again (Limits)
`HumanInteractionComplete`	a person has replied, and the run is waiting for a worker to carry on
`PendingApproval`	waiting for a person to approve a tool call
`AwaitingChildren`	waiting for sub-interactions it started
`Finished`	done: the answer is in `output`
`Error`	failed, or ran out of time: the reason is in `failureDetails`
`Killed`	stopped by someone, or because the run that started it was stopped

See them in tutorial 4, Runs: start a run without waiting, read it back, and watch its status change.

Who a message is from

Every message a person adds to a chat is saved with an author, a name and an id, and the agents see the name with the message (Ana (Human User): …). Who the author is depends on how the caller signs in:

The caller signs in with	The message is recorded as
an API key, naming no author	the API key’s own user
an API key, naming an author	exactly that name and id
a person’s own sign-in (the portal, or `mt api-login user`)	always that person; a named author is ignored

So an app that talks to Maitento for its users, with one API key, can say which of its users wrote each message. The id is the app’s own, any GUID; an author named without an id is recorded with an id of all zeros. See it in tutorial 7, A chat.

Other properties

Property	What it does
`functions.openApi`	tools available to every agent in the interaction
`schema.solution`	the JSON Schema the answer must match: see Structured output
`duration.warn`, `duration.max`	a time warning for the agents and a hard stop, as `"hh:mm:ss"`. See Limits
`context`	how the conversation is trimmed when it no longer fits the model. See Limits
`loom`	long-term memory
`swarm`	other interactions this one may start as sub-runs
`prompts.system`	extra system instructions for every agent in the interaction