Agent profiles service¶

`consortium.server.services.agent_profiles_service` ¶

`AgentProfilesService(release_service, paths_service)` ¶

`get_agent_profile_from_directory(directory, ignore_enabled_flag=False)` ¶

Instantiates an agent profile from a directory without registering it.

Disabled agent profiles (as indicated by enabled: false in their manifest.json) are not instantiated unless ignore_enabled_flag is True.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Path to the directory containing the agent profile project files and `manifest.json`.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`AgentProfile \| None`	The instantiated agent profile, or `None` if the profile is disabled and the enabled check is not overridden.

Raises:

Type	Description
`AgentProfileManifestFileNotFoundError`	If `manifest.json` is missing.
`InvalidAgentProfileManifestFileJSONError`	If `manifest.json` contains invalid JSON.
`InvalidAgentProfileManifestFileSchemaError`	If `manifest.json` does not follow the expected schema.
`InvalidAgentProfilePyProjectFileTOMLError`	If `pyproject.toml` is not valid TOML.
`InvalidAgentProfilePyProjectFileDependencyError`	If `pyproject.toml` contains an invalid dependency entry.
`AgentProfileEntryPointModuleNotFoundError`	If the entry-point module specified in the manifest cannot be found.
`AgentProfileSymbolNotFoundError`	If the symbol specified in the manifest is not found in the entry-point module.
`AgentProfileInterfaceError`	If the agent profile class does not correctly inherit from the expected base class.
`IncompatibleAgentProfileFrameworkVersionError`	If the profile is incompatible with the current framework version.
`InternalAgentProfileError`	If an unhandled exception occurs while loading the profile.

`get_all_agent_profiles_from_directory(directory, ignore_enabled_flag=False)` ¶

Recursively scans a directory for agent profiles and instantiates them.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	The directory to scan for agent profiles.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in each profile's manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`list[AgentProfile]`	A three-element tuple: (1) a list of successfully instantiated agent
`list[Path]`	profiles, (2) a list of paths skipped because the profile was disabled,
`list[tuple[Path, AgentProfileLoadingError]]`	and (3) a list of `(path, error)` tuples for profiles that failed to
`tuple[list[AgentProfile], list[Path], list[tuple[Path, AgentProfileLoadingError]]]`	load.

Raises:

Type	Description
`AgentProfileDiscoveryFileSystemError`	If the recursive filesystem scan of `directory` fails, for example because a subdirectory is removed mid-scan or cannot be read due to a permissions error. This happens before any individual agent profile is loaded, so it is not one of the per-profile errors collected in the returned error list, it propagates to the caller.

`load_agent_profile(agent_profile)` `async` ¶

Registers and activates an already-instantiated agent profile.

After loading, agent type references across all profiles are resolved, and the compatible agent type index for listener profiles is updated.

Parameters:

Name	Type	Description	Default
`agent_profile`	`AgentProfile`	The agent profile instance to load.	required

Raises:

Type	Description
`AgentProfileAlreadyRegisteredError`	If an agent profile with the same ID is already registered in the agent profiles service.
`DuplicateAgentTypeNameError`	If the loaded profile's agent type name collides with a distinct agent type already registered under the same name while agent type references are resolved.
`UnresolvableAgentTypeReferenceError`	If any registered profile's `agent_type` is a string reference that cannot be resolved to a registered agent type while agent type references are resolved.
`TypeError`	If a registered profile's `agent_type` is a string reference that resolves to another agent profile. The resolver in `c2_types_service` then attempts to call that profile as a constructor, which is not callable, so this is raised whenever the string-reference resolution path is taken.

`load_agent_profile_from_directory(directory, ignore_enabled_flag=False)` `async` ¶

Loads an agent profile from a directory, registering and activating it.

Disabled profiles are skipped unless ignore_enabled_flag is True. After a successful load, agent type references and the compatible agent type index for listener profiles are updated.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Path to the directory containing the agent profile project files and `manifest.json`.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`AgentProfile \| None`	The loaded agent profile, or `None` if the profile is disabled and the enabled check is not overridden.

Raises:

Type	Description
`AgentProfileManifestFileNotFoundError`	If `manifest.json` is missing.
`InvalidAgentProfileManifestFileJSONError`	If `manifest.json` contains invalid JSON.
`InvalidAgentProfileManifestFileSchemaError`	If `manifest.json` does not follow the expected schema.
`AgentProfileEntryPointModuleNotFoundError`	If the entry-point module cannot be found.
`AgentProfileSymbolNotFoundError`	If the symbol specified in the manifest is not found.
`AgentProfileInterfaceError`	If the class does not inherit from the expected base class.
`IncompatibleAgentProfileFrameworkVersionError`	If the profile is incompatible with the current framework version.
`InternalAgentProfileError`	If an unhandled exception occurs while loading the profile.
`AgentProfileAlreadyRegisteredError`	If an agent profile with the same ID is already registered in the agent profiles service.
`DuplicateAgentTypeNameError`	If the loaded profile's agent type name collides with a distinct agent type already registered under the same name while agent type references are resolved.
`UnresolvableAgentTypeReferenceError`	If any registered profile's `agent_type` is a string reference that cannot be resolved to a registered agent type while agent type references are resolved.
`TypeError`	If a registered profile's `agent_type` is a string reference that resolves to another agent profile. The resolver in `c2_types_service` then attempts to call that profile as a constructor, which is not callable, so this is raised whenever the string-reference resolution path is taken.

`unload_agent_profile_by_agent_profile_id(agent_profile_id)` `async` ¶

Deactivates and deregisters a loaded agent profile by its ID.

After unloading, the compatible agent type index for listener profiles is updated to reflect the removal.

Parameters:

Name	Type	Description	Default
`agent_profile_id`	`str \| UUID`	The ID of the agent profile to unload.	required

Raises:

Type	Description
`AgentProfileNotFoundError`	If no agent profile with the given ID is registered.

`reload_agent_profile_by_agent_profile_id(agent_profile_id, ignore_enabled_flag=False)` `async` ¶

Unloads and reloads an agent profile from its original directory.

After a successful reload, agent type references and the compatible agent type index for listener profiles are updated. If the profile is disabled after reload and ignore_enabled_flag is False, the profile will only be unloaded, not reloaded.

Parameters:

Name	Type	Description	Default
`agent_profile_id`	`str \| UUID`	The ID of the agent profile to reload.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest during reload. Defaults to `False`.	`False`

Returns:

Type	Description
`AgentProfile \| None`	The reloaded agent profile instance, or `None` if the profile was disabled and the enabled check was not overridden.

Raises:

Type	Description
`AgentProfileNotFoundError`	If no agent profile with the given ID is registered.
`AgentProfileManifestFileNotFoundError`	If `manifest.json` is missing from the profile's directory at the time of reload.
`InvalidAgentProfileManifestFileJSONError`	If `manifest.json` contains invalid JSON at the time of reload.
`InvalidAgentProfileManifestFileSchemaError`	If `manifest.json` does not follow the expected schema at the time of reload.
`AgentProfileEntryPointModuleNotFoundError`	If the entry-point module specified in the manifest cannot be found at the time of reload.
`AgentProfileSymbolNotFoundError`	If the symbol specified in the manifest is not found at the time of reload.
`AgentProfileInterfaceError`	If the class does not inherit from the expected base class at the time of reload.
`IncompatibleAgentProfileFrameworkVersionError`	If the profile is incompatible with the current framework version at the time of reload.
`InternalAgentProfileError`	If an unhandled exception occurs while reloading the profile.
`AgentProfileAlreadyRegisteredError`	If an agent profile with the same ID is already registered in the agent profiles service.
`DuplicateAgentTypeNameError`	If the reloaded profile's agent type name collides with a distinct agent type already registered under the same name while agent type references are resolved.
`UnresolvableAgentTypeReferenceError`	If any registered profile's `agent_type` is a string reference that cannot be resolved to a registered agent type while agent type references are resolved.
`TypeError`	If a registered profile's `agent_type` is a string reference that resolves to another agent profile. The resolver in `c2_types_service` then attempts to call that profile as a constructor, which is not callable, so this is raised whenever the string-reference resolution path is taken.

`load_framework_agent_profiles(ignore_enabled_flag=False)` `async` ¶

Scans the framework's agent profiles directory and loads all enabled profiles.

Disabled profiles and profiles that fail to load are logged and skipped without aborting the overall load.

Parameters:

Name	Type	Description	Default
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in each profile's manifest. Defaults to `False`.	`False`

Raises:

Type	Description
`AgentProfileDiscoveryFileSystemError`	If the framework agent profiles directory cannot be scanned (for example, due to a permissions error) while discovering candidate agent profile directories.
`DuplicateAgentTypeNameError`	If a loaded profile's agent type name collides with a distinct agent type already registered under the same name while agent type references are resolved. Per-profile loading failures wrapped in `AgentTemplatesFrameworkError` or `AgentProfilesServiceError` are caught and logged without aborting the overall load, but this error is neither.
`UnresolvableAgentTypeReferenceError`	If any registered profile's `agent_type` is a string reference that cannot be resolved to a registered agent type while agent type references are resolved. Not caught by the per-profile error handling for the same reason as above.
`TypeError`	If a registered profile's `agent_type` is a string reference that resolves to another agent profile. The resolver in `c2_types_service` then attempts to call that profile as a constructor, which is not callable, so this is raised whenever the string-reference resolution path is taken. Not caught by the per-profile error handling for the same reason as above.

`unload_framework_agent_profiles()` `async` ¶

Unloads all agent profiles that were loaded from the framework's profiles directory.

Raises:

Type	Description
`AgentProfileNotFoundError`	If an agent profile is deregistered between being listed and being unloaded.

`reload_framework_agent_profiles()` `async` ¶

Unloads all framework agent profiles then reloads them from the profiles directory.

Raises:

Type	Description
`AgentProfileNotFoundError`	If an agent profile is deregistered between being listed and being unloaded, during the unload half.
`AgentProfileDiscoveryFileSystemError`	If the framework agent profiles directory cannot be scanned during the load half.
`DuplicateAgentTypeNameError`	If a loaded profile's agent type name collides with a distinct agent type already registered under the same name while agent type references are resolved, during the load half.
`UnresolvableAgentTypeReferenceError`	If any registered profile's `agent_type` is a string reference that cannot be resolved to a registered agent type while agent type references are resolved, during the load half.
`TypeError`	If a registered profile's `agent_type` is a string reference that resolves to another agent profile. The resolver in `c2_types_service` then attempts to call that profile as a constructor, which is not callable, so this is raised whenever the string-reference resolution path is taken during the load half.

`get_all_agent_profiles()` ¶

Returns all currently loaded agent profiles.

Returns:

Type	Description
`list[AgentProfile]`	A list of all loaded agent profiles. Empty if none are loaded.

`get_agent_profile_by_agent_profile_id(agent_profile_id)` ¶

Returns a loaded agent profile by its ID.

Parameters:

Name	Type	Description	Default
`agent_profile_id`	`str \| UUID`	The ID of the agent profile to retrieve.	required

Returns:

Type	Description
`AgentProfile`	The requested agent profile.

Raises:

Type	Description
`AgentProfileNotFoundError`	If no agent profile with the given ID is registered.

Agent profiles service¶

consortium.server.services.agent_profiles_service ¶