Agent generators service¶

`consortium.server.services.agent_generators_service` ¶

`AgentGeneratorsService(agent_templates_service, events_service)` ¶

`get_agent_generator_by_agent_generator_id(agent_generator_id)` ¶

Returns an agent generator by its ID.

Parameters:

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

Returns:

Type	Description
`BaseAgentGenerator`	The requested agent generator.

Raises:

Type	Description
`AgentGeneratorNotFoundError`	If no agent generator with the given ID exists.

`get_all_agent_generators()` ¶

Returns all agent generators currently held by the service.

Returns:

Type	Description
`list[BaseAgentGenerator]`	A list of all agent generators. Empty if none exist.

`create_agent_generator_from_agent_template_by_agent_template_id(agent_template_id, parameters, name=None, description='')` ¶

Creates and registers a new agent generator from the specified agent template.

Emits an AGENT_GENERATOR_CREATED event.

Parameters:

Name	Type	Description	Default
`agent_template_id`	`str \| UUID`	The ID of the agent template to create the agent generator from.	required
`parameters`	`dict[str, Any]`	Build parameters to pass to the agent template when creating the agent generator.	required
`name`	`str \| None`	An optional display name for the new agent generator. If omitted, a random human-readable name is generated.	`None`
`description`	`str`	An optional description for the new agent generator.	`''`

Returns:

Type	Description
`BaseAgentGenerator`	The newly created agent generator instance.

Raises:

Type	Description
`AgentTemplateIDNotFoundError`	If no agent template with the given ID is found.
`MissingRequiredAgentTemplateOptionError`	If a required template option is absent from parameters.
`AgentTemplateOptionNotFoundError`	If parameters contains an option name the template does not declare.
`AgentTemplateOptionValueValidationError`	If a parameter value fails type or constraint validation.
`AgentTemplateValidatingFunctionError`	If the template's validating function rejects the resolved option set.
`AgentGeneratorCreationParameterTypeError`	If `name` is not a string, or if `description` or the resolved `parameters` fail type validation when the agent generator instance is constructed.

Note that every option validation error above is raised by the template before the agent generator is instantiated, so nothing is registered and no AGENT_GENERATOR_CREATED event is emitted when one occurs.

`add_agent_generator(agent_generator)` ¶

Adds an already-instantiated agent generator to the service.

Unlike create_agent_generator_from_agent_template_by_agent_template_id, this method accepts a pre-built agent generator instance rather than creating one from a template. Emits an AGENT_GENERATOR_ADDED event.

Parameters:

Name	Type	Description	Default
`agent_generator`	`BaseAgentGenerator`	The agent generator instance to add.	required

Raises:

Type	Description
`AgentGeneratorAlreadyExistsError`	If an agent generator with the same ID is already registered.

`remove_agent_generator_by_agent_generator_id(agent_generator_id)` ¶

Removes an agent generator from the service.

Emits an AGENT_GENERATOR_REMOVED event. The agent generator must not currently be running; stop it first before removing.

Parameters:

Name	Type	Description	Default
`agent_generator_id`	`str \| UUID`	The ID of the agent generator to remove.	required

Raises:

Type	Description
`AgentGeneratorNotFoundError`	If no agent generator with the given ID exists.
`AgentGeneratorAlreadyRunningError`	If the agent generator is currently running.

`update_agent_generator_by_agent_generator_id(agent_generator_id, name=None, description=None, parameters=None)` ¶

Updates the name, description, and/or parameters of an agent generator.

Parameter updates are applied atomically: if validation of any parameter fails, no other updates are applied. When parameters is provided, missing keys are back-filled from the existing parameter set so only the specified fields change. Emits an AGENT_GENERATOR_UPDATED event when at least one field changes.

Parameters:

Name	Type	Description	Default
`agent_generator_id`	`str \| UUID`	The ID of the agent generator to update.	required
`name`	`str \| None`	The new display name. When `None`, the name is not changed.	`None`
`description`	`str \| None`	The new description. When `None`, the description is not changed.	`None`
`parameters`	`dict[str, Any] \| None`	A partial or full mapping of parameter names to new values. When `None`, parameters are not changed.	`None`

Returns:

Type	Description
`BaseAgentGenerator`	The updated agent generator instance.

Raises:

Type	Description
`AgentGeneratorNotFoundError`	If no agent generator with the given ID exists.
`AgentGeneratorAlreadyRunningError`	If a parameter update is attempted while the agent generator is running.
`InvalidAgentGeneratorParameterNameError`	If a key in `parameters` is not a valid parameter for the creating agent template.
`InvalidAgentGeneratorParameterValueError`	If a value in `parameters` fails validation against the creating agent template.
`AgentTemplateValidatingFunctionError`	If the creating agent template's validating function rejects the resolved parameter set.
`AgentGeneratorCreationParameterTypeError`	If the resolved parameter set fails type validation while the replacement agent generator is constructed.

`start_agent_generator_by_agent_generator_id(agent_generator_id, blocking=False)` `async` ¶

Starts an agent generator by its ID.

Emits an AGENT_GENERATOR_STARTED event after starting.

Parameters:

Name	Type	Description	Default
`agent_generator_id`	`str \| UUID`	The ID of the agent generator to start.	required
`blocking`	`bool`	If `True`, waits until the agent generator has fully started before returning. Defaults to `False`.	`False`

Raises:

Type	Description
`AgentGeneratorNotFoundError`	If no agent generator with the given ID exists.
`AgentGeneratorAlreadyRunningError`	If the agent generator is already in a running state.
`AgentGeneratorStartError`	If the agent generator fails to start.
`AgentGeneratorFatalError`	If an unhandled exception escapes the agent generator's `on_started` hook, leaving it in a fatal state.

`stop_agent_generator_by_agent_generator_id(agent_generator_id, blocking=False)` `async` ¶

Stops an agent generator by its ID.

Emits an AGENT_GENERATOR_STOPPED event after stopping.

Parameters:

Name	Type	Description	Default
`agent_generator_id`	`str \| UUID`	The ID of the agent generator to stop.	required
`blocking`	`bool`	If `True`, waits until the agent generator has fully stopped before returning. Defaults to `False`.	`False`

Raises:

Type	Description
`AgentGeneratorNotFoundError`	If no agent generator with the given ID exists.
`AgentGeneratorNotRunningError`	If the agent generator is not currently running.
`AgentGeneratorStopError`	If the agent generator fails to stop cleanly.
`AgentGeneratorFatalError`	If an unhandled exception escapes the agent generator's `on_stopped` hook, leaving it in a fatal state.

`cancel_agent_generator_by_agent_generator_id(agent_generator_id, blocking=False)` `async` ¶

Cancels an agent generator by its ID, forcibly aborting it.

Unlike stopping, cancellation does not wait for the agent generator to finish its current operation cleanly. Emits an AGENT_GENERATOR_CANCELLED event.

Parameters:

Name	Type	Description	Default
`agent_generator_id`	`str \| UUID`	The ID of the agent generator to cancel.	required
`blocking`	`bool`	If `True`, waits until the agent generator has fully stopped before returning. Defaults to `False`.	`False`

Raises:

Type	Description
`AgentGeneratorNotFoundError`	If no agent generator with the given ID exists.
`AgentGeneratorNotRunningError`	If the agent generator is not currently running.
`AgentGeneratorFatalError`	If an unhandled exception escapes the agent generator's `on_cancelled` hook, leaving it in a fatal state.

Agent generators service¶

consortium.server.services.agent_generators_service ¶