Codex CLI

UseCodex(...) selects local Codex CLI execution. Runiq launches the CLI under the host account, using its existing authentication and configuration. You do not supply an agent API key.

Define the Codex agent

Install Runiq.AI.Agents in a .NET 10 ASP.NET Core project. Codex requires a configuration callback with an explicit model: calling UseCodex() without arguments is a compile-time error. Leaving options.Model blank inside the callback fails validation when creating the definition.

Create Agents/CodexAgent.cs. This factory follows the repository sample and sets the model, reasoning effort, and service tier explicitly:

using Runiq.AI.Agents;
using Runiq.AI.Agents.Configuration;

namespace MyApp.Agents;

/// <summary>Defines the read-only repository assistant backed by the local Codex CLI.</summary>
public static class CodexAgent
{
    /// <summary>Creates the repository inspection agent using existing Codex CLI authentication.</summary>
    /// <returns>The configured Codex agent; no API key is required.</returns>
    public static Agent Create() => new Agent(
        id: "codex-agent",
        name: "CodeReviewer",
        instructions: """
        You are CodeReviewer, a read-only coding assistant for the current project.
        Respond to the user's actual request, in the user's language.
        For a greeting or a question about your capabilities, reply briefly and offer
        examples; do not inspect files or run commands just because a conversation started.
        For a code question, inspect only the relevant files in the current working directory.
        Explain a named file, trace a requested behavior, review supplied code, or suggest
        a change with an illustrative code snippet or diff in your reply.
        Cite the relative file paths and line numbers supporting repository-specific findings.
        If the request is unclear or requires a missing file, ask a short clarifying question.
        Do not claim to have read files or run checks that you have not actually performed.
        Treat each request as self-contained; ask for missing context instead of assuming chat history.
        Never modify files, run destructive commands, commit, or push.
        For implementation requests, provide a proposal in the answer without applying it.
        Keep the answer concise and focused on the requested task.
        """)
        .UseCodex(options =>
        {
            options.Model = "gpt-6-astra";
            options.ReasoningEffort = CodexReasoningEffort.High;
            options.ServiceTier = CodexServiceTier.Default;
        });
}

The instructions keep the assistant focused on the current request and make repository inspection deliberate. Instructions do not enforce filesystem permissions; the Codex executor uses a read-only sandbox by default.

Register the agent

In Program.cs, create the definition through the factory and register it before building the host:

using MyApp.Agents;
using Runiq.AI.Agents.Configuration;
using Runiq.AI.Core;

var builder = WebApplication.CreateBuilder(args);
var agent = CodexAgent.Create();

builder.Services.AddRuniqServer(options => options.AddAgent(agent));

var app = builder.Build();
app.Run();

AddRuniqServer automatically registers the Codex executor. Definition and registration do not launch or authenticate the CLI. To execute this agent, follow Running agents using codex-agent as the agent id, or enable Studio and select CodeReviewer.

Choose model settings

There is no parameterless UseCodex() overload. Use the CLI model name without the openai/ provider prefix used by model-provider agents. Availability and supported reasoning levels depend on the installed CLI and account; Runiq does not maintain a model catalog. Settings are copied into agent.Executor!.Codex and applied on new and resumed turns.

Attach Runiq tools

Attach a typed tool to the definition before registration:

using Runiq.AI.Agents.Tools;

// Use TextStatsTool from the Defining tools guide.
agent.AddTool<TextStatsTool>();

See Defining tools for the complete TextStatsTool definition. Runiq automatically exposes the agent's tools through a per-run MCP bridge; no additional MCP server registration is required. Tool calls appear in Studio using the existing tool events.

Tool code runs in the host process with host permissions, outside the CLI sandbox. Authorize and validate operations inside the tool. Native Codex tool activity is not published as Runiq tool events. Active Runiq RAG bindings are unsupported and return CodexCapabilityNotSupported.

Execute and continue a conversation

Use AgentExecutionRuntime for both completed results and streaming. Codex emits completed assistant messages as deltas; token-by-token streaming is not guaranteed. A later turn can use the confirmed ProviderSessionId; see CLI conversation continuation.

Missing installation returns CodexNotInstalled; authentication failure returns CodexAuthenticationFailed. Rejected models and reasoning combinations return CodexModelNotAvailable and CodexReasoningEffortNotSupported. CLI failures do not fall back to another executor.

Next: Run the registered agent →