Defining agents

This guide creates the model-based support-agent used throughout the Agents documentation. You need a .NET 10 ASP.NET Core application and a configured model provider for this example. For local CLI execution, see Codex CLI or Claude CLI.

Install the package

Run this in the project that defines and executes agents:

dotnet add package Runiq.AI.Agents

The Agents package references Core and includes the agent runtime. For a new solution, you can also follow Get Started.

Register the agent

Add the definition before building the host:

using Runiq.AI.Agents;
using Runiq.AI.Core;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRuniqServer(options =>
{
    options.AddAgent(new Agent(
        id: "support-agent",
        name: "Support Agent",
        instructions: """
            Help users understand the application.
            Ask for missing details before giving specific guidance.
            Keep answers concise and state uncertainty clearly.
            """,
        model: "openai/gpt-5",
        apiKey: builder.Configuration["OpenAI:ApiKey"]));
});

var app = builder.Build();

app.Run();

The runtime can now resolve support-agent. Registration alone does not send a request to the model. Configure your key using Model and provider, then follow Running agents to add an endpoint.

Select an executor

The constructor above selects model execution. Alternatively, use the three-argument constructor and select the executor explicitly:

var agent = new Agent("support-agent", "Support Agent", "Help users understand the application.")
    .UseModel("openai/gpt-5", apiKey: builder.Configuration["OpenAI:ApiKey"]);

Use UseCodex(options => options.Model = "gpt-6-astra") for Codex CLI, or UseClaude(options => options.Model = "sonnet") for Claude CLI. Both require an explicit model; see the Claude guide for API availability and migration from the old parameterless method. Start those definitions with the three-argument constructor as well. A definition can select exactly one executor; selecting again throws InvalidOperationException. Finish selection before the AddRuniqServer callback returns.

CLI executor registration is automatic when you add those agents through AddRuniqServer. CLI installation and authentication are required when executing a request, not when creating or registering the definition.

Choose identity and instructions

Keep the id stable after callers depend on it. See Instructions for guidance you can test.

Add capabilities deliberately

Tools let the agent request application operations. Define a typed tool, then attach it with AddTool<TTool>(). All three executors support attached Runiq tools; the CLI executors expose them through an automatic MCP bridge. Tools execute with host permissions. Follow Defining tools for the contract and registration.

RAG supplies relevant document passages for model execution. Active Runiq RAG bindings are unsupported by the CLI executors. After configuring and ingesting a named index, connect it to an existing model-agent definition:

agent.UseRag(rag =>
{
    rag.IndexName = "product-docs";
});

This does not create or ingest the index. The default policy allows normal answers when no context is accepted. Choose the grounding and no-context policy explicitly for source-dependent answers in Defining indexes.

Keep the first definition small

Start with one responsibility and verify a response before attaching more capabilities. Move definitions into separate files when they grow; Patterns shows how.

Next: Configure the model connection →