Running agents

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

The same runtime APIs execute Codex CLI and Claude CLI agents. Use their registered id in place of support-agent. Keep the invoking DI scope alive until execution or stream disposal completes.

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. Model execution with missing required credentials can return ApiKeyMissing. CLI executors report installation and authentication errors such as CodexNotInstalled, ClaudeNotInstalled, CodexAuthenticationFailed, or ClaudeAuthenticationFailed. Inspect the completed result's success state or a stream's failure event; CLI failure does not fall back to a model provider.

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.

For an unregistered CLI definition, its matching executor must already be registered in the host. AddRuniqServer automatically registers CLI infrastructure only for the CLI kinds selected by the agents in its registration callback. A runtime missing the matching executor returns AgentExecutorNotSupported.

Continue a CLI conversation

Every invocation receives a fresh RunId. To continue CLI history, use the confirmed ProviderSessionId from a previous successful result:

using Runiq.AI.Agents.Runtime;

var first = await runtime.ExecuteAsync(
    "codex-agent", "Explain the entry point.", cancellationToken);

if (first.IsSuccess && first.ProviderSessionId is { } sessionId)
{
    var next = await runtime.ExecuteAsync(
        "codex-agent",
        new AgentQuery("Suggest tests for that entry point.")
        {
            ProviderSessionId = sessionId
        },
        cancellationToken);
}

The same pattern works with claude-analyst. A RunId is not a provider session key. The host must authorize session ownership and bind it to the correct agent and workspace. Concurrent execution of the same session within one host is rejected. Calls without ProviderSessionId start a fresh CLI conversation.

Continuation is available through AgentQuery; Studio chat does not expose a continuation control or HTTP request session field. Interactive approval waiting and resumption are unsupported.

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 →