14. Model and tool tasks

Model tasks

LLM_CHAT sends messages to a model and returns its reply. The engine treats it like any other activity: recorded, retried, timed out, and visible in history with its input and output.

{ "taskReferenceName": "review", "type": "LLM_CHAT",
  "inputParameters": {
    "model": "default-reasoning",
    "instructions": "${instructions.engagement_review@2}",
    "context": "${load.output}",
    "responseSchema": { "type": "object", "properties": { "summary": {}, "risk": {} } },
    "maxTokens": 2000 } }

instructions refers to a versioned text in the instruction registry, so the exact prompt used by every run is recorded. responseSchema asks the model for JSON in a fixed shape, which later tasks read by reference.

AI gateway

The gateway sits between the engine and Foundry. Its AI policies apply per workflow, keyed on the x-yml-workflow header: token quotas, a semantic cache, model routing, and prompt logging. Azure AI Content Safety checks inputs and outputs when a task sets contentSafety: true.

Tools and trust tiers

A tool is an action on the action service, exposed through the gateway with the MCP protocol. Tools are grouped in trust tiers, each on its own endpoint:

Tier	Contents	Rule
Read	Queries that change nothing	No gate required
Write	Actions that change records	A HUMAN task must precede the call on every path, unless autonomy: true
High-risk	Actions with external or financial effect	As write, and the workflow uses its own identity

LIST_TOOLS returns the tools available to the workflow's tier. CALL_TOOL calls one. The pipeline derives each workflow's allowed tool list from its definition and deploys it to the gateway as policy.

Proposal and execution

A model never calls a tool directly. The pattern is:

1. LLM_CHAT with the tool list. The model replies with toolCalls: which tool and which arguments.
2. Optionally a HUMAN or SWITCH task that checks the proposal.
3. CALL_TOOL with the proposed arguments.

Because the call is a separate task, a gate, a validation, or a rule can sit between the proposal and the action. The registration check on page 4 enforces the gate for write-tier tools.

Agents

An agent is a model that decides step by step what to do. In this engine an agent is control flow:

DO_WHILE (maxIterations from the task)
    LIST_TOOLS
    LLM_CHAT      instructions, history, tool list
    SWITCH on ${llm.output.toolCalls}
        present -> CALL_TOOL for each; SET_VARIABLE history
        absent  -> SET_VARIABLE done = true

Every turn is a recorded task. The iteration bound, the tool list, and any human gate are in the definition, not in the prompt. A crash mid-loop resumes from the last completed turn.

External agents

An external agent is a program hosted outside the engine that runs its own loop: it calls a model as often as it needs, uses its own tools, keeps its own memory, and returns a result. Examples: an agent built in Foundry Agent Service or Copilot Studio. The engine calls it as one step with CALL_AGENT.

{ "taskReferenceName": "research", "type": "CALL_AGENT",
  "inputParameters": {
    "agent": "research-assistant",
    "prompt": "${workflow.input.question}",
    "context": "${load.output}",
    "timeoutSeconds": 1800 } }

Field	Meaning
agent	Name of an agent registered on the gateway
prompt	The goal
context	Optional structured input passed with the goal
executionId	Resumes an earlier call instead of starting a new one
timeoutSeconds	Limit for the whole call, default 24 hours

Output: executionId, state (completed, failed, canceled, input-required), text, and output when the agent returns structured data.

Protocol

Agents are called over A2A (Agent2Agent), the open protocol for sending a task to an agent and following it to completion. The activity sends the goal, receives an execution id, and polls the agent until the state is terminal, at intervals set on the task. A crash of the engine mid-call resumes polling the same execution id. Agents that do not speak A2A are wrapped by a small adapter that does.

Registration

An agent is registered on the gateway like a tool: a name, an endpoint, a trust tier, and the identity the engine uses to call it. The pipeline checks at registration that every agent named in a definition exists on the gateway for the workflow's tier. The gateway records every call with the workflow name and version.

Pauses and cancellation

When the agent needs input, the call completes with state: input-required and the question in text. The workflow collects the answer, with a HUMAN task or otherwise, and issues another CALL_AGENT with the same executionId and the answer as prompt. Terminating the run sends a cancel to any agent call still in progress.

Limits

The engine records the call as one step: goal in, result out. What the agent did in between is held in the agent's own logs. A CALL_AGENT step that names an agent in the write or high-risk tier is subject to the same human-gate rule as CALL_TOOL.