Running agents

Agents are executed by AgentExecutionRuntime, not by calling the Agent instance directly.

The Agent class still contains direct execution methods, but the implementation returns DirectAgentExecutionNotSupported. Use the runtime service from dependency injection.

Run by agent id

using Runiq.Agents.Runtime;

app.MapPost("/ask-weather", async (
    WeatherQuestion request,
    AgentExecutionRuntime runtime,
    CancellationToken cancellationToken) =>
{
    var result = await runtime.ExecuteAsync(
        agentId: "weather-agent",
        input: request.Message,
        cancellationToken);

    return result.IsSuccess
        ? Results.Ok(new { message = result.Message })
        : Results.BadRequest(new
        {
            errorCode = result.ErrorCode,
            errorMessage = result.ErrorMessage
        });
});

public sealed record WeatherQuestion(string Message);

If the runtime cannot find the id, it returns an AgentNotFound failure result.

Stream by agent id

using Runiq.Agents;
using Runiq.Agents.Runtime;

app.MapPost("/ask-weather/events", async (
    WeatherQuestion request,
    AgentExecutionRuntime runtime,
    CancellationToken cancellationToken) =>
{
    await foreach (AgentExecutionEvent executionEvent in runtime.ExecuteStreamAsync(
                       agentId: "weather-agent",
                       input: request.Message,
                       cancellationToken: cancellationToken))
    {
        // Write to your UI transport, logger, or response stream.
        Console.WriteLine($"{executionEvent.Kind}: {executionEvent.Content}");
    }

    return Results.Accepted();
});

Runtime event kinds are:

Event kind	Meaning
`AssistantDelta`	Partial assistant text.
`ToolCallStarted`	The model requested an attached tool.
`ToolCallCompleted`	A typed .NET tool completed and returned JSON output.
`ToolCallFailed`	A tool call failed.
`Completed`	Agent execution completed successfully.
`Failed`	Agent execution failed.
`ContextProvided`	Context Space metadata was attached to the run.
`ContextSearched`	Attached source documents were searched for the run.
`SkillLoaded`	Context Space skill instructions were loaded.

Run an ad hoc agent

AgentExecutionRuntime also supports executing an Agent instance directly:

var agent = new Agent(
    id: "temporary-agent",
    name: "Temporary Agent",
    instructions: "Answer briefly.",
    model: "openai/gpt-5",
    apiKey: builder.Configuration["OpenAI:ApiKey"]);

var result = await runtime.ExecuteAsync(
    agent,
    "Explain the runtime flow in one paragraph.",
    cancellationToken);

Use registered agents for normal application behavior. Registered agents are easier to inspect through metadata and the dashboard.

Dashboard chat endpoint

UseRuniqDashboard maps the dashboard agent API under the configured dashboard path.

With the default dashboard path /runiq, the chat endpoint is:

HTTP

POST /runiq/api/agents/{agentId}/chat
Content-Type: application/json

{
  "message": "What should I wear in Istanbul today?",
  "responseMode": "Stream"
}

If you configure the dashboard at /dashboard, the endpoint becomes:

HTTP

POST /dashboard/api/agents/{agentId}/chat

responseMode is a JSON string enum:

Value	Response
`Stream`	Server-sent events with `data: ...` lines and a final `data: [DONE]`. This is the default.
`Result`	One JSON response containing success state, final message, error details, and execution steps.

Stream event payloads

The dashboard chat stream maps runtime events to lowercase string event types.

Stream `type`	Main fields
`assistant_delta`	`content`
`tool_call_started`	`toolCallId`, `toolName`, `argumentsJson`
`tool_call_completed`	`toolCallId`, `toolName`, `outputJson`
`tool_call_failed`	`toolCallId`, `toolName`, `errorCode`, `errorMessage`
`context_provided`	`contextSpaces`, `skills`, `sources`
`skill_loaded`	`loadedSkills`
`context_searched`	`contextSearchSummary`, `sourceSearchResults`
`completed`	Completion marker before `[DONE]`.
`failed`	`content`, `errorCode`, `errorMessage`

Tool output is not the final answer. It is returned to the model so the model can continue and produce the final assistant response.