Patterns

Move beyond inline registration when definitions become difficult to review. Keep configuration separate from the application operations an agent can request.

Put a definition in its own file

A small factory is enough; inheriting from Agent is not required.

using Runiq.AI.Agents;

internal static class SupportAgent
{
    internal static Agent Create(string? apiKey) => new(
        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: apiKey);
}

Register it in Program.cs:

builder.Services.AddRuniqServer(options =>
{
    options.AddAgent(
        SupportAgent.Create(builder.Configuration["OpenAI:ApiKey"]));
});

Keep required capability attachments in the factory so callers receive the same definition.

Organize by responsibility

Agents/
  SupportAgent.cs
Tools/
  ProductLookupTool.cs
Program.cs

Agent files describe behavior and allowed capabilities. Tools implement application operations. RAG configuration defines indexes and retrieval policies.

A second agent is useful when it has a distinct responsibility or capability boundary. Multiple agents do not automatically collaborate; your application must define invocation and information passing.

Group registration when it grows

An application-owned helper can group related definitions:

using Runiq.AI.Core.Configuration;

internal static class AgentRegistration
{
    internal static void AddSupportAgents(
        this RuniqServerOptions options,
        string? apiKey)
    {
        options.AddAgent(SupportAgent.Create(apiKey));
    }
}

Call options.AddSupportAgents(apiKey) inside AddRuniqServer. This is an application organization choice, not a required framework abstraction.

Keep capability boundaries explicit

• Attach only the tools the agent needs.
• Enforce authorization and validation inside application services.
• Keep document ingestion and index setup outside instructions.
• Use stable ids for registered agents.
• Test changed definitions with representative requests.

Avoid duplicate configuration

Keep provider keys in configuration. Reuse a definition factory rather than copying instructions across startup code, endpoints, and tests.

Use Studio testing to inspect behavior and Running agents for the execution API.