AI Agent — Input & Output

Output Ports

Port	Triggered When	Data Available
success	The agent produced a final answer before hitting `max_turns`. The model declared the goal complete.	Full output object: `result`, `reasoning`, `tool_calls`, `turns_used`, `model_used`
error	The agent hit `max_turns` without completing, a tool invocation failed fatally, or the model API returned an error.	`error_message`, `error_code`, `turns_used`, `partial_reasoning` (reasoning trace up to the point of failure)

Output Data Schema — success port

Field	Type	Description
`result`	string / object	The agent's final answer. May be a plain text string or structured JSON depending on how the agent was instructed to respond via `system_prompt`.
`reasoning`	string	Full chain-of-thought text produced by the agent across all turns. Useful for debugging and audit. Not returned to end users unless deliberately included.
`tool_calls`	array	Ordered list of every tool the agent invoked. Each element contains `tool_name`, `inputs`, `output`, and `turn_number`.
`turns_used`	integer	How many reasoning turns were executed. Compare against `max_turns` to detect near-limit runs.
`model_used`	string	The model ID that was actually used (useful when using model aliases or fallback logic).
`tokens_input`	integer	Total input tokens consumed across all turns.
`tokens_output`	integer	Total output tokens generated across all turns.

tool_calls Array — Item Schema

Field	Type	Description
`turn_number`	integer	Which reasoning turn this tool call occurred in (1-indexed).
`tool_name`	string	Name of the tool that was invoked.
`inputs`	object	The input parameters the agent passed to the tool. Matches the tool's registered input schema.
`output`	any	The result returned by the tool to the agent.
`success`	boolean	`true` if the tool completed without error, `false` if the tool returned an error (the agent may recover and try differently).
`duration_ms`	integer	Wall-clock time the tool took to execute in milliseconds.

Expression Paths for Downstream Nodes

After the FlowAiAgent node, use the following BizFirst expressions to access output data in downstream node configurations:

Expression	Returns
`{@ $node.agentNode.result }`	The agent's final answer (string or object)
`{@ $node.agentNode.reasoning }`	Full reasoning trace text
`{@ $node.agentNode.turns_used }`	Number of turns used
`{@ $node.agentNode.tool_calls }`	Full tool call array
`{@ $node.agentNode.tool_calls[0].tool_name }`	Name of the first tool called
`{@ $node.agentNode.tool_calls[0].output }`	Output of the first tool call
`{@ $node.agentNode.model_used }`	Model that executed the agent
`{@ $node.agentNode.tokens_input }`	Total input tokens

Structured result output: For predictable downstream processing, instruct the agent to respond in JSON via the system_prompt: "Your final answer must be a valid JSON object matching this schema: …". Then access individual fields with expressions like {@ $node.agentNode.result.customerSentiment }.

Example Output — Success

{
  "result": {
    "resolution": "Order #ORD-8821 was delayed due to a warehouse issue. A replacement has been dispatched. Expected delivery: 2026-05-27.",
    "action_taken": "sent_apology_email",
    "escalation_required": false
  },
  "reasoning": "Turn 1: I need to look up the customer account to understand their order history...\nTurn 2: The lookupAccount tool returned account tier: Premium. I will now check order status...\nTurn 3: checkOrderStatus returned 'delayed'. I will search the knowledge base for the standard resolution policy...\nTurn 4: Policy says Premium customers get immediate replacement. I will send an apology email and dispatch replacement.",
  "tool_calls": [
    {
      "turn_number": 1,
      "tool_name": "lookupAccount",
      "inputs": { "customer_id": "CUST-4421" },
      "output": { "name": "Acme Corp", "tier": "Premium", "status": "active" },
      "success": true,
      "duration_ms": 120
    },
    {
      "turn_number": 2,
      "tool_name": "checkOrderStatus",
      "inputs": { "order_id": "ORD-8821" },
      "output": { "status": "delayed", "reason": "warehouse_capacity", "eta": "2026-05-27" },
      "success": true,
      "duration_ms": 98
    },
    {
      "turn_number": 3,
      "tool_name": "searchKnowledgeBase",
      "inputs": { "query": "delayed order resolution policy premium customer" },
      "output": { "policy": "Dispatch replacement immediately, send apology email with compensation voucher" },
      "success": true,
      "duration_ms": 205
    },
    {
      "turn_number": 4,
      "tool_name": "sendEmail",
      "inputs": {
        "to": "contact@acmecorp.com",
        "subject": "Your order ORD-8821 — update and resolution",
        "body": "We sincerely apologise for the delay..."
      },
      "output": { "sent": true, "message_id": "msg-99123" },
      "success": true,
      "duration_ms": 310
    }
  ],
  "turns_used": 4,
  "model_used": "claude-sonnet-4",
  "tokens_input": 4820,
  "tokens_output": 1104
}

Example Output — Error (max_turns reached)

{
  "error_message": "Agent reached max_turns (8) without completing the goal.",
  "error_code": "MAX_TURNS_EXCEEDED",
  "turns_used": 8,
  "partial_reasoning": "Turn 1: Looking up account...\nTurn 2: Account lookup failed with timeout...\nTurn 3: Retrying lookup...\n..."
}

Error port handling: Always connect a handler to the error port. At minimum, log the error_message and partial_reasoning to your audit system and trigger an alert. For customer-facing workflows, route the error port to a graceful fallback response rather than surfacing the raw error to the end user.

Using result as a Structured JSON Object

When the agent's system_prompt instructs it to respond in JSON, the result field is automatically parsed into a workflow object. You can then access individual fields directly:

// Agent system_prompt: "Your final response must be valid JSON with fields: category, priority, queue_id"

// Access structured fields downstream:
{@ $node.agentNode.result.category }
{@ $node.agentNode.result.priority }
{@ $node.agentNode.result.queue_id }

If the agent does not produce valid JSON (e.g. it wraps the JSON in markdown code fences), the result field is returned as a plain string. Add explicit instructions like "Respond with ONLY a JSON object — no markdown, no explanation, just the raw JSON" to ensure reliable parsing.

Inspecting tool_calls for Debugging

The tool_calls array is the primary debugging surface for agent workflows. When an agent produces unexpected results, examine:

tool_name sequence — did the agent call the right tools in the expected order?
inputs per tool — did the agent construct the tool parameters correctly from the available context?
output per tool — did the tool return the expected data? If output is empty or wrong, the issue is likely in the tool's implementation or data, not the agent.
success flags — were any tools marked success: false? The agent may have attempted recovery, or it may have proceeded with incomplete data.
turns_used — if turns_used == max_turns, the agent ran out of turns. Increase max_turns or simplify the goal.

token Usage Monitoring

Field	What to Watch For
`tokens_input`	Grows with each turn as context accumulates. High values (>20,000) indicate the agent is using many turns or has very long tool outputs. Consider summarising tool outputs in the tool definition.
`tokens_output`	Reflects the volume of reasoning text and final answer generated. Very high values may mean the agent is over-explaining — tighten the system_prompt to be more concise.
`turns_used`	If consistently close to `max_turns`, either increase the limit or decompose the goal into simpler sub-tasks using multiple agent nodes in sequence.

Chaining agents: For very complex goals that require more than 15–20 tool calls, consider decomposing the goal into two sequential FlowAiAgent nodes. The first agent collects and prepares data; the second agent analyses and produces the final output. Pass the first agent's result as the context for the second agent.