Class AgentSpecSync

constructor

• new AgentSpecSync(
      spec?: Partial<AgentSpec>,
      contextUser?: UserInfo,
      provider?: IMetadataProvider,
  ): AgentSpecSync

  Create a new AgentSpecSync instance.

  Note: This constructor is typically not called directly. Instead, use the static factory methods:

  • LoadFromDatabase - Load existing agent from database
  • LoadByName - Load agent by name
  • FromRawSpec - Create from raw spec data

  Parameters

  • Optionalspec: Partial<AgentSpec>

    Optional initial spec data (for creating new agents or working with existing data)

  • OptionalcontextUser: UserInfo

    Optional context user (required for server-side operations)

  • Optionalprovider: IMetadataProvider

  Returns AgentSpecSync

spec

isDirty

• get isDirty(): boolean

  Check if this spec has unsaved changes.

  Returns boolean

  True if there are unsaved changes, false otherwise

isLoaded

• get isLoaded(): boolean

  Check if this spec has been loaded from the database.

  Returns boolean

  True if loaded from database, false if created in memory

clearMutations

• clearMutations(): void

  Clear all tracked mutations

  Returns void

getMutations

• getMutations(): AgentSpecSyncMutation[]

  Get all mutations tracked during the last save operation

  Returns AgentSpecSyncMutation[]

  Array of mutations

markDirty

• markDirty(): void

  Mark the spec as having changes.

  Call this method after modifying the spec to indicate that changes need to be saved. The spec is automatically marked dirty when created with the constructor, but if you load a spec and then modify it, you should call this method.

  Returns void

  Example

  const spec = await AgentSpecSync.LoadFromDatabase('agent-uuid', contextUser);
  spec.spec.Description = 'New description';
  spec.markDirty();
  await spec.SaveToDatabase();
  Copy

markLoaded

• markLoaded(): void
  Internal

  Mark the spec as having been loaded from the database.

  This is used internally when updating existing child agents to ensure the delete logic runs correctly. When a child agent is updated via saveChildSubAgent(), we create a new AgentSpecSync instance from the spec data (not loaded from DB), but we need to mark it as loaded so orphaned records are properly deleted.

  Returns void

  Example

  const childSync = new AgentSpecSync(existingChildSpec, contextUser);
  childSync.markDirty();
  childSync.markLoaded();  // Ensure delete logic runs for existing agent
  await childSync.SaveToDatabase();
  Copy

SaveToDatabase

• SaveToDatabase(validate?: boolean): Promise<AgentSpecSyncResult>

  Save the current spec to the database.

  This will create new records or update existing ones based on whether IDs exist. The save operation is performed atomically - if any part fails, no changes are committed.

  Validation is performed before saving. All entity-level validations defined in the database schema are executed, and any failures will prevent the save.

  Parameters

  • validate: boolean = true

    Whether to validate before saving (default: true)

  Returns Promise<AgentSpecSyncResult>

  Promise resolving to result with agent ID, success flag, and all mutations performed

  Throws

  If validation fails or save operation fails

  Example

  const spec = new AgentSpecSync({
      Name: 'New Agent',
      InvocationMode: 'Any'
  }, contextUser);
  
  const result = await spec.SaveToDatabase();
  console.log('Saved with ID:', result.agentId);
  console.log('Mutations:', result.mutations.length);
  Copy

toJSON

• toJSON(): AgentSpec

  Get a clean serializable version of the spec.

  Returns a plain JavaScript object suitable for JSON serialization, API responses, or storage. This is useful when you need to send the agent spec over the wire or store it in a file.

  Returns AgentSpec

  Clean copy of the agent specification

  Example

  const spec = await AgentSpecSync.LoadFromDatabase('agent-uuid', contextUser);
  const json = spec.toJSON();
  res.json(json); // Send as API response
  Copy

StaticFromRawSpec

• FromRawSpec(
      rawSpec: AgentSpec,
      contextUser?: UserInfo,
      provider?: IMetadataProvider,
  ): AgentSpecSync

  Create a new agent spec from a raw specification.

  This creates an in-memory AgentSpecSync instance from raw data. The agent is not saved to the database until SaveToDatabase is called.

  Parameters

  • rawSpec: AgentSpec

    The raw spec data conforming to AgentSpec interface

  • OptionalcontextUser: UserInfo

    Optional context user (required when saving server-side)

  • Optionalprovider: IMetadataProvider

  Returns AgentSpecSync

  New AgentSpecSync instance (not yet saved to database)

  Example

  const rawSpec: AgentSpec = {
      ID: '',
      Name: 'New Agent',
      Description: 'Agent description',
      InvocationMode: 'Any',
      Actions: [],
      SubAgents: []
  };
  const spec = AgentSpecSync.FromRawSpec(rawSpec, contextUser);
  await spec.SaveToDatabase();
  Copy

StaticLoadByName

• LoadByName(
      agentName: string,
      contextUser?: UserInfo,
      includeSubAgents?: boolean,
      provider?: IMetadataProvider,
  ): Promise<AgentSpecSync>

  Load an agent by name (must be unique).

  Searches for an agent with the specified name and loads it. If multiple agents have the same name, an error is thrown. Agent names should be unique within the system for this method to work reliably.

  Parameters

  • agentName: string

    The name of the agent to load

  • OptionalcontextUser: UserInfo

    Optional context user (required for server-side operations)

  • includeSubAgents: boolean = true

    Whether to recursively load sub-agents (default: true)

  • Optionalprovider: IMetadataProvider

  Returns Promise<AgentSpecSync>

  Promise resolving to AgentSpecSync instance with loaded data

  Throws

  If agent is not found or multiple agents have the same name

  Example

  const spec = await AgentSpecSync.LoadByName('My Agent', contextUser);
  Copy

StaticLoadFromDatabase

• LoadFromDatabase(
      agentId: string,
      contextUser?: UserInfo,
      includeSubAgents?: boolean,
      provider?: IMetadataProvider,
  ): Promise<AgentSpecSync>

  Load an agent and its complete hierarchy from the database by ID.

  This method efficiently loads the agent along with all its actions and sub-agents using batched queries to minimize database round trips. When includeSubAgents is true, it recursively loads the entire agent hierarchy.

  Parameters

  • agentId: string

    The unique ID of the agent to load

  • OptionalcontextUser: UserInfo

    Optional context user (required for server-side operations)

  • includeSubAgents: boolean = true

    Whether to recursively load all sub-agents (default: true)

  • Optionalprovider: IMetadataProvider

  Returns Promise<AgentSpecSync>

  Promise resolving to AgentSpecSync instance with loaded data

  Throws

  If agent with specified ID is not found

  Example

  // Load agent with all sub-agents
  const spec = await AgentSpecSync.LoadFromDatabase(
      'agent-uuid-here',
      contextUser,
      true
  );
  Copy