Runtime and events
Understand input binding, tool results, and the events emitted during execution.
During an agent run, the model requests a tool by its registered name. Runiq invokes an attached tool and returns its result to the model.
How invocation works
- Resolve the tool from the agent's attached registrations.
- Deserialize JSON arguments into the input type.
- Create the tool using the invocation service provider.
- Call its public
ExecuteAsyncmethod. - Serialize the output to JSON and return it to the model.
The model may continue with another tool request or an answer. A completed tool call does not by itself mean the agent run has completed.
Runtime events and HTTP events
The C# runtime and Studio HTTP stream use different event names:
| C# event kind | Studio stream type | Payload |
|---|---|---|
ToolCallStarted | tool_call_started | Call id, tool name, JSON arguments |
ToolCallCompleted | tool_call_completed | Call id, tool name, JSON output |
ToolCallFailed | tool_call_failed | Call id, tool name, error details |
An agent run also emits assistant text and completion or failure events. See Running agents for the complete stream reference and consumption examples.
Failure reference
| Code | Meaning |
|---|---|
ToolNameRequired | The requested name is empty. |
ToolNotFound | The requested tool is not attached to the selected agent. |
ToolInputInvalid | JSON binding failed or produced a null input. |
ToolExecutionFailed | Invocation failed, including dependency resolution or implementation exceptions. |
A business validation exception is not automatically classified as ToolInputInvalid. That code describes JSON binding failures. For example, the whitespace check in TextStatsTool results in ToolExecutionFailed when invoked through the tool invoker.
The invoker returns a generic execution failure message and logs exception details on the server. Do not rely on exception text being returned to the model or Studio.
Handle outcomes explicitly
For expected business outcomes, consider a structured output such as a found/not-found result. Do not fabricate successful data when an operation fails.
During an agent run, a failed tool call can be returned to the model as error information for continuation. Inspect the final run outcome rather than assuming every tool failure ends the whole run.
Pass cancellation through
Accept the supplied cancellation token and pass it to asynchronous application services. Check it before expensive work. This lets the operation participate in the caller's cancellation behavior.