Manage rooms__AIModel__c Agent Configuration Records

This public behavioral and data-model reference covers subscriber-visible iDialogue configuration records in Salesforce. Its original subscriber examples do not grant access, configure a connector, or authorize a change; Salesforce permissions, workspace instructions, and visitor decisions control what can run.

Before using an example, describe the connected-org objects. Installed versions, field access, and model or skill values can differ from this reference.

Configuration model

erDiagram
    rooms__AIModel__c ||--o{ rooms__AIPrompt__c : "instructions and Quick Starts"
    rooms__AIModel__c ||--o{ rooms__AISkill__c : "configured skills"
    rooms__AIContextDefinition__c ||--o{ rooms__AIModel__c : "optional data context"

rooms__AIContext__c is runtime/materialized context and is not an authoring object covered by these examples.

Agent lifecycle and identity

rooms__Stage__c is a restricted lifecycle value: Draft, Discovery, or Published. New Agent Studio agents use Draft. rooms__IsActive__c separately controls display in the AI Assistant console; it is not a publication or authorization flag. Verify both values for the intended surface.

Agent, prompt, and skill Name values are not unique. Select an existing record by Id after showing the user the matching candidates. rooms__UniqueID__c, rooms__LatestPackageID__c, and package URL fields support packaging and installation; do not use them as general authoring keys.

Create a Draft agent

This synthetic Apex example mirrors the current Agent Studio starting profile. Check the connected org before relying on model aliases or field values.

rooms__AIModel__c agent = new rooms__AIModel__c(
    Name = 'Account Research Assistant',
    rooms__SObjectType__c = 'Account',
    rooms__Audience__c = 'Internal',
    rooms__Description__c = 'Summarizes approved Account context.',
    rooms__Stage__c = 'Draft',
    rooms__IsActive__c = true,
    rooms__OpenAIModel__c = 'prime',
    rooms__ReasoningEffort__c = 'medium',
    rooms__Verbosity__c = 'medium',
    rooms__ToolChoice__c = 'auto',
    rooms__BatchConcurrency__c = '1',
    rooms__BackgroundTimeoutSeconds__c = 600,
    rooms__MaxResponseSize__c = 5000,
    rooms__IncludeAllSObjectLabelsValues__c = true,
    rooms__IncludeAllSObjectMetadata__c = false,
    rooms__SystemPrompt__c = '# Mission\nSummarize the supplied Account using approved context.'
);
insert agent;

For a Global agent, Agent Studio normally disables automatic record-label/value inclusion. Keep the root instruction stable and put modular rules in related System Instructions.

Update the root Agent record

Query only the fields needed for the task, then update by Id. Common documented settings include identity, description, audience, object type, Data Context binding, Chat and Background model settings, response limits, working status, and the root rooms__SystemPrompt__c.

update new rooms__AIModel__c(
    Id = agentId,
    rooms__Description__c = 'Summarizes and compares approved Account context.',
    rooms__SystemPrompt__c = revisedRootInstruction
);

Changing rooms__Stage__c is a separate lifecycle operation. Do not infer publication from a successful settings update.

Add a System Instruction

A System Instruction is active runtime instruction content, not a clickable Quick Start.

insert new rooms__AIPrompt__c(
    Name = 'Account evidence rules',
    rooms__Label__c = 'Account evidence rules',
    rooms__AIModel__c = agentId,
    rooms__Prompt__c = 'Separate Salesforce facts from external research.',
    rooms__RunContext__c = 'All',
    rooms__Order__c = 10,
    rooms__IsSystemPrompt__c = true,
    rooms__IsSuggested__c = false,
    rooms__IsAction__c = false,
    rooms__IsActive__c = true
);

Valid Run Context values are All, Chat, and Background. Use separate instructions when interactive and background behavior differ.

Add a Quick Start

Quick Starts are suggested user prompts. They do not replace the agent's root or related System Instructions.

insert new rooms__AIPrompt__c(
    Name = 'Summarize this account',
    rooms__Label__c = 'Summarize this account',
    rooms__AIModel__c = agentId,
    rooms__Prompt__c = 'Summarize this Account and identify missing evidence.',
    rooms__DisplayOrder__c = 10,
    rooms__Order__c = 10,
    rooms__IsSystemPrompt__c = true,
    rooms__IsSuggested__c = true,
    rooms__IsAction__c = true,
    rooms__IsPrivate__c = true,
    rooms__IsActive__c = true
);

Agent Studio limits the Quick Start label to 80 characters and requires a prompt body.

Add and manage a catalog-backed skill

Choose the exact primitive API name and category from the current Skills Catalog. Do not invent a function name or copy a tool definition into the skill prompt.

insert new rooms__AISkill__c(
    Name = 'Query SObjects',
    rooms__AIModel__c = agentId,
    rooms__ArchetypeFunction__c = 'query_sobjects',
    rooms__Category__c = 'Salesforce',
    rooms__RunContext__c = 'All',
    rooms__Order__c = 10,
    rooms__IsActive__c = true
);

For an existing skill, normal configuration changes use rooms__RunContext__c, rooms__Order__c, and rooms__IsActive__c. A configured skill makes a tool available; its runtime permissions and behavior still come from the connected services and agent instructions.

update new rooms__AISkill__c(
    Id = skillId,
    rooms__RunContext__c = 'Background',
    rooms__Order__c = 20,
    rooms__IsActive__c = true
);

Bind an existing Data Context Definition

Use the Data Context Definition guide to understand its JSON contract. Treat rooms__DefinitionKey__c as opaque. Bind an existing definition by Salesforce record ID:

update new rooms__AIModel__c(
    Id = agentId,
    rooms__DataContextDefinition__c = dataContextDefinitionId
);

Connector-neutral record shape

A Salesforce coding connector may express the same operation as an object API name plus fields. Tool names and envelopes vary, so use its documented schema rather than assuming a particular MCP payload:

{
  "object": "rooms__AIModel__c",
  "operation": "update",
  "recordId": "<agent Salesforce Id>",
  "fields": {
    "rooms__Description__c": "Revised description",
    "rooms__SystemPrompt__c": "# Mission\nRevised instruction"
  }
}

Verify the result

1. Re-query the changed record and its intended relationships by Id.
2. Reopen the same agent in Agent Studio and confirm the values persisted.
3. Test a low-risk Chat or Background scenario through its intended browser or Flow entry point.
4. Verify the expected Dialogue, record change, file, or other business result.

Agent, prompt, skill, and Data Context Definition writes can schedule downstream synchronization. Salesforce DML success proves only the Salesforce transaction succeeded; it does not prove remote synchronization or runtime readiness.

These examples intentionally omit deletes, bulk mutation, automatic publication, rooms__RunAsUser__c, runtime rooms__AIContext__c, package/install identity, telemetry, formula fields, raw vector identifiers, and internal transport or orchestration fields.

Related guides

• Run an Agent from Apex with rooms.AIAgent
• Run Agent Action (AI) for Salesforce Flow
• Customize an Agent in Agent Studio
• System and Local Agents