Agents service¶
consortium.server.services.agents_service
¶
AgentsService(events_service, tasks_service, task_runtime_service)
¶
register_agent(listener_id, registration_message=None, payload_id=None, agent_type=None, name=None, description='', endpoint='', user=None, is_admin=None, os=None, version=None, arch=None, pid=None, locale=None, remote_ip=None, local_ip=None, hostname=None, agent_data=None)
¶
Registers a new agent and emits an AGENT_REGISTERED event.
Give the agent's reported details either as a whole registration_message or as
individual fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
listener_id
|
str | UUID
|
The ID of the listener this agent is connecting through. |
required |
registration_message
|
RegistrationMessageModel | None
|
The registration details reported by the agent. When given, it supplies every reported field and the individual field arguments below are ignored. Nothing an agent reports is verified by the server, so treat the contents as claims rather than as facts. |
None
|
payload_id
|
str | UUID | None
|
The ID of the payload that generated this agent. When |
None
|
agent_type
|
str | None
|
The agent type name. When |
None
|
name
|
str | None
|
A human-readable display name for the agent. When |
None
|
description
|
str
|
A short human-readable description of the agent. Defaults to an empty string when omitted. |
''
|
endpoint
|
str
|
A human-readable string identifying the agent's network endpoint. Defaults to an empty string when omitted. |
''
|
user
|
str | None
|
The OS username the agent process is running as. When |
None
|
is_admin
|
bool | None
|
Whether the agent is running with administrator or root privileges.
When |
None
|
os
|
str | None
|
The name of the host operating system (for example "Windows"). When
|
None
|
version
|
str | None
|
The version string of the host operating system. When |
None
|
arch
|
str | None
|
The CPU architecture of the host system (for example "x86_64"). When
|
None
|
pid
|
int | None
|
The process ID of the agent on its host. When |
None
|
locale
|
str | None
|
The locale string of the host system (for example "en_US"). When
|
None
|
remote_ip
|
str | None
|
The IP address the agent is reachable at. When |
None
|
local_ip
|
str | None
|
The local IP address of the agent's host as seen by the agent
itself. When |
None
|
hostname
|
str | None
|
The hostname of the agent's host. When |
None
|
agent_data
|
dict[str, Any] | None
|
Arbitrary key-value pairs carrying agent-specific metadata not
covered by the other fields. When |
None
|
Returns:
| Type | Description |
|---|---|
Agent
|
The newly registered agent instance. |
Raises:
| Type | Description |
|---|---|
AgentCreationParameterTypeError
|
If any of the provided parameters is not of the type the agent expects. |
ListenerNotFoundError
|
If no listener with the given |
AgentTypeResolutionError
|
If the agent's type cannot be resolved, either
because neither |
deregister_agent_by_agent_id(agent_id)
¶
Removes a registered agent from the service and emits an AGENT_DEREGISTERED event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The ID of the agent to deregister. |
required |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
If no agent with the given ID is registered. |
delete_agent_by_agent_id(agent_id)
async
¶
Deletes a registered agent from the service and emits an AGENT_DELETED event.
Unlike deregister_agent_by_agent_id, which reflects an agent that has left of
its own accord, this is an operator-initiated removal of the agent regardless of
whether it is still active.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The ID of the agent to delete. |
required |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
If no agent with the given ID is registered. |
check_in_agent_by_agent_id(agent_id)
¶
Records a check-in from an agent, updating its last activity timestamp and marking it active.
Emits an AGENT_CHECKED_IN event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The ID of the agent checking in. |
required |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
If no agent with the given ID is registered. |
get_next_task_message_by_task_id(agent_id, task_id, timeout=None)
async
¶
Get the next task message produced by a running capability of an agent for a specific task.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to read the task message from. |
required |
task_id
|
str | UUID
|
The task ID of the running task whose next message to read. |
required |
timeout
|
float | None
|
Maximum time in seconds to wait for the next message. If None, waits indefinitely. If 0, polls without blocking. |
None
|
Returns:
| Type | Description |
|---|---|
TaskInputMessageModel | TaskOutputMessageModel | None | object
|
The next task message produced by the task's capability, |
TaskInputMessageModel | TaskOutputMessageModel | None | object
|
elapsed before a message was produced (poll again), or END_OF_STREAM if the |
TaskInputMessageModel | TaskOutputMessageModel | None | object
|
capability has finished and its outbox is fully drained (move on). |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
AgentTaskNotFoundError
|
Raised if the task with the specified task ID is not found on the agent. |
get_next_task_message_sequential(agent_id, timeout=None)
async
¶
Get the next task message from the earliest running capability of an agent.
Messages are drained from the earliest started capability until it completes before moving on to the next one, preserving a strict per-capability ordering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to read the task message from. |
required |
timeout
|
float | None
|
Maximum time in seconds to wait for the next message, spanning both the wait for a capability to start and the wait for it to produce a message. If None, waits indefinitely. If 0, polls without blocking. |
None
|
Returns:
| Type | Description |
|---|---|
TaskInputMessageModel | TaskOutputMessageModel | None
|
The next task message from the earliest running capability, or None if the |
TaskInputMessageModel | TaskOutputMessageModel | None
|
timeout elapsed before a message was produced. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
get_next_task_message_any(agent_id, timeout=None)
async
¶
Get the next task message from any running capability of an agent.
Returns the first message produced by any running capability, interleaving (muxing) messages across capabilities in the order they become available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to read the task message from. |
required |
timeout
|
float | None
|
Maximum time in seconds to wait for the next message, spanning both the wait for a capability to start and the wait for one to produce a message. If None, waits indefinitely. If 0, polls without blocking. |
None
|
Returns:
| Type | Description |
|---|---|
TaskLaunchMessageModel | TaskOutputMessageModel | None
|
The next task message from any running capability, or None if the timeout |
TaskLaunchMessageModel | TaskOutputMessageModel | None
|
elapsed before a message was produced. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
drain_task_messages_by_task_id(agent_id, task_id)
async
¶
Drain task messages from a specific running task of an agent until it completes.
Yields each message produced by the task's capability in order, terminating when the capability finishes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to drain task messages from. |
required |
task_id
|
str | UUID
|
The task ID of the running task whose messages to drain. |
required |
Yields:
| Type | Description |
|---|---|
AsyncGenerator[TaskLaunchMessageModel | TaskInputMessageModel]
|
Each task message produced by the task's capability, in the order produced. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
AgentTaskNotFoundError
|
Raised if the task with the specified task ID is not found on the agent. |
drain_task_messages_sequential(agent_id)
async
¶
Drain task messages from an agent one capability at a time.
Yields messages from the earliest started capability until it completes before moving on to the next one, preserving a strict per-capability ordering. Loops indefinitely, waiting for new capabilities to start as needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to drain task messages from. |
required |
Yields:
| Type | Description |
|---|---|
AsyncGenerator[TaskLaunchMessageModel | TaskInputMessageModel]
|
Each task message, drained from the earliest running capability first. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
drain_task_messages_any(agent_id)
async
¶
Drain task messages from any running capability of an agent.
Yields messages from any running capability, interleaving (muxing) them in the order they become available. Loops indefinitely, waiting for new capabilities to start as needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to drain task messages from. |
required |
Yields:
| Type | Description |
|---|---|
AsyncGenerator[TaskLaunchMessageModel | TaskInputMessageModel]
|
Each task message, in the order it becomes available across all running |
AsyncGenerator[TaskLaunchMessageModel | TaskInputMessageModel]
|
capabilities. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
dispatch_task_output_message(agent_id, task_output_message=None, task_id=None, success=None, message='', data=None, payload=None)
async
¶
Dispatch a task output message for a running task on an agent.
Give the agent's reported result either as a whole task_output_message or as
individual fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The agent ID of the agent to submit the result for. |
required |
task_output_message
|
TaskOutputMessageModel | None
|
The task output message reported by the agent, identifying the task it belongs to and carrying any result data and binary payload. When given, the individual field arguments below are ignored. |
None
|
task_id
|
str | UUID | None
|
The task ID of the task to submit the result for. Required when
|
None
|
success
|
bool | None
|
Whether the task was successful. Required when
|
None
|
message
|
str
|
A message describing the result. |
''
|
data
|
dict[str, Any] | None
|
The result data. |
None
|
payload
|
Payload | bytes | bytearray | None
|
Optional binary payload associated with the result. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
Raised if neither |
AgentNotFoundError
|
Raised if the agent with the specified agent ID is not found. |
ValidationError
|
Raised if the arguments provided fail validation of the
task output message they are assembled into, for example a |
Note
A task output message whose task ID does not correspond to a running task (the task completed, timed out or was deleted) is a benign lifecycle race, it is logged and dropped rather than raised.
get_agent_by_agent_id(agent_id)
¶
Returns a registered agent by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The ID of the agent to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
Agent
|
The agent with the specified ID. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
If no agent with the given ID is registered. |
get_all_agents()
¶
Returns all registered agents.
Returns:
| Type | Description |
|---|---|
list[Agent]
|
A list of all registered agents. Empty if none are registered. |
task_agent_by_agent_id(agent_id, command, arguments)
async
¶
Queues a command for execution on the specified agent and emits an AGENT_TASKED event.
The tasking is validated before any task is created. When validation rejects it
no task is registered and no AGENT_TASKED event is emitted, the relevant
exception below is raised instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The ID of the agent to task. |
required |
command
|
str
|
The name of the command to execute on the agent. |
required |
arguments
|
dict[str, Any]
|
The arguments to pass along with the command. Omitted optional options are filled in from their declared defaults. |
required |
Returns:
| Type | Description |
|---|---|
Task
|
The newly created task object representing the queued command. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
If no agent with the given ID is registered. |
AgentCapabilityNotFoundError
|
If command does not name a capability of the agent's type. |
MissingRequiredAgentCapabilityOptionError
|
If a required option is absent from arguments. |
AgentCapabilityOptionNotFoundError
|
If arguments contains an unknown option name. |
AgentCapabilityOptionValueValidationError
|
If an argument value fails type or constraint validation. |
AgentCapabilityValidatingFunctionError
|
If the capability's validating function rejects the resolved argument set. |
update_agent_by_agent_id(agent_id, name=None, description=None)
¶
Updates the name and/or description of a registered agent.
Emits an AGENT_UPDATED event when at least one field changes. Passing None
for a field leaves it unchanged.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id
|
str | UUID
|
The ID of the agent to update. |
required |
name
|
str | None
|
The new display name for the agent. When |
None
|
description
|
str | None
|
The new description for the agent. When |
None
|
Returns:
| Type | Description |
|---|---|
Agent
|
The updated agent instance. |
Raises:
| Type | Description |
|---|---|
AgentNotFoundError
|
If no agent with the given ID is registered. |