Running agents

Resolve AgentExecutionRuntime through dependency injection. Use it to run the support-agent registered in Defining agents.

Return one completed response

Add this endpoint before app.Run(). Put the record declaration after the top-level statements.

using Runiq.AI.Agents.Runtime;

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

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

public sealed record SupportQuestion(string Message);

Send a JSON body such as { "message": "How can I describe a problem clearly?" } to POST /ask. This example returns the runtime result; choose HTTP status codes and error disclosure appropriate to your application.

Consume streaming events

The runtime also produces an asynchronous event stream. In a handler or service with an injected runtime, consume it as follows:

await foreach (var executionEvent in runtime.ExecuteStreamAsync(
    agentId: "support-agent",
    input: "Help me describe a problem clearly.",
    cancellationToken: cancellationToken))
{
    Console.WriteLine(
        $"{executionEvent.Kind}: {executionEvent.Content}");
}

This example logs events. To stream to a browser, connect the events to your transport or use the Studio chat endpoint described below.

Handle failures and cancellation

An unknown registered id returns AgentNotFound. Missing required credentials can return ApiKeyMissing. Inspect the completed result's success state or a stream's failure event.

Pass the caller's cancellation token through to execution. Let your endpoint or service handle cancellation consistently with the rest of the application.

Call the runtime rather than Agent.ExecuteAsync; direct execution on the definition returns DirectAgentExecutionNotSupported.

Execute an unregistered definition

For an ad hoc run, pass an existing Agent definition:

var result = await runtime.ExecuteAsync(
    agent,
    "Explain this feature briefly.",
    cancellationToken);

Use registered definitions for normal application behavior when callers and Studio need to discover them by id.

Runtime event reference

Tool output is returned to the model for continuation; it is not necessarily the final answer.

Studio HTTP endpoint

With Studio hosted at /dashboard, its agent endpoint is:

POST /dashboard/api/agents/support-agent/chat
Content-Type: application/json

{
  "message": "Help me describe a problem clearly.",
  "responseMode": "Stream"
}

The default dashboard path is /runiq; the endpoint follows the configured path. Studio authentication applies. See Studio hosting.

Stream event types

Next: Inspect a run in Studio →