Overview
Understand what a Runiq Agent is in a .NET application.
A Runiq Agent is an AI runtime component that lives inside your .NET application.
Most LLM integrations start as one prompt and one HTTP call. That works for a demo, but it breaks down when the AI feature becomes part of a real product. Developers need stable identities, reusable instructions, provider configuration, typed application capabilities, source-backed context, streaming events, and a way to debug what happened after the model responds.
Runiq turns that into a first-class .NET concept. An agent is registered in your ASP.NET Core host, configured in C#, attached to typed tools, optionally connected to Context Spaces, executed by the Runiq runtime, and visible in Studio. The AI behavior becomes something your application owns instead of a loose prompt hidden behind a controller action.
For .NET developers, the advantage is control. You can keep business capabilities in C#, keep dependency injection, keep model/provider configuration close to the agent, and still give the model enough runtime power to call tools and produce useful answers.
Why agents matter
Use an agent when your application needs AI behavior that can interpret a user request, decide whether a tool is needed, call application-owned capabilities, use source-backed context, and synthesize a final answer.
The important shift is that the agent is no longer just "some prompt text." It becomes a named runtime unit with a contract. It can be tested, inspected, reused in workflows, and reasoned about by other developers on the team.
For example, a support application can define a Support Agent that uses product docs, a Customer Lookup Tool, and escalation rules. A finance application can define an Expense Analyst Agent with policy context and typed expense search. A travel sample can define Weather, Places, and Planner agents. The domain changes, but the pattern is the same: focused AI behavior registered inside the .NET app.
What an agent contains
| Part | Purpose |
|---|---|
id | Stable runtime identifier used for lookup, dashboard routes, HTTP calls, workflows, and metadata. |
name | Human-readable label shown in the dashboard. |
instructions | System-level guidance sent to the model during execution. |
model | Provider and model reference in provider/model format. |
apiKey | Optional constructor value used by providers that require authorization. |
provider | Optional provider runtime options such as custom URL and timeout. |
reasoningEffort | Runtime behavior value: minimal, low, medium, or high. |
verbosity | Runtime behavior value: low, medium, or high. |
| tools | Typed .NET tools attached with AddTool<TTool>(). |
| context spaces | Optional source-backed context attached with UseContextSpace(...). |
Runtime flow
The user message does not magically "go to the agent" by itself. It reaches the Runiq runtime, which looks up the registered agent definition and builds the provider request from the agent's configuration.
| Step | What happens |
|---|---|
| 1 | A user message reaches the Runiq runtime through the dashboard API, your app, or AgentExecutionRuntime. |
| 2 | The runtime finds the registered agent by its stable id. |
| 3 | The runtime builds the model request using the agent instructions, user message, model/provider config, runtime options, context, and attached tool schemas. |
| 4 | The provider either answers directly or requests a tool call. |
| 5 | If a tool call is requested, Runiq executes the attached typed .NET tool. |
| 6 | The tool result is sent back to the model for continuation. |
| 7 | The final assistant response is produced and can be streamed as execution events. |
Agents, tools, workflows, and context
Agents decide and synthesize. Tools execute deterministic application behavior. Workflows define a fixed execution order. Context Spaces provide source-backed knowledge.
These pieces are designed to work together:
| Runtime concept | Use it for |
|---|---|
| Agent | Open-ended interpretation, tool selection, synthesis, and assistant responses. |
| Tool | Typed .NET operations such as calling an API, querying a database, or calculating a value. |
| Workflow | Fixed multi-step execution where the application owns the order. |
| Context Space | Source-backed knowledge that can be searched and added to agent context. |