Connected agents service¶

`consortium.server.services.connected_agents_service` ¶

`ConnectedAgentsService(listener_id)` ¶

A thin service wrapper around AgentsService that provides listener-scoped agent operations. This service ensures that all agent operations are validated against the listener that owns this service instance, and automatically handles agent check-ins where appropriate.

This service is intended to be used by listeners to interact with agents that are connected to them. It provides a higher-level abstraction over the AgentsService that simplifies common listener operations like retrieving tasks and submitting results.

`register_agent(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)` ¶

Register a new agent with this listener.

Give the agent's reported details either as a whole registration_message or as individual fields. Nothing the agent reports is verified by the server, so treat the details as claims about the host rather than as facts.

Parameters:

Name	Type	Description	Default
`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.	`None`
`payload_id`	`str \| UUID \| None`	The payload ID of the payload that the agent is using to connect to the listener.	`None`
`agent_type`	`str \| None`	The name of the agent type to register the agent as.	`None`
`name`	`str \| None`	The human-readable name of the agent.	`None`
`description`	`str`	A description of the agent.	`''`
`endpoint`	`str`	A human-readable representation of the network endpoint that uniquely identifies the agent.	`''`
`user`	`str \| None`	The name of the user account that the agent is running on.	`None`
`is_admin`	`bool \| None`	Whether the agent is running with administrator privileges.	`None`
`os`	`str \| None`	The operating system of the agent.	`None`
`version`	`str \| None`	The version of the operating system.	`None`
`arch`	`str \| None`	The architecture of the system.	`None`
`pid`	`int \| None`	The process ID of the agent.	`None`
`locale`	`str \| None`	The locale of the system.	`None`
`remote_ip`	`str \| None`	The remote host address of the agent.	`None`
`local_ip`	`str \| None`	The local host address of the agent.	`None`
`hostname`	`str \| None`	The hostname of the system.	`None`
`agent_data`	`dict[str, Any] \| None`	Additional data from the agent.	`None`

Raises:

Type	Description
`AgentTypeResolutionError`	Raised if the agent type cannot be resolved from the reported payload ID or agent type.
`AgentCreationParameterTypeError`	Raised if a parameter has an invalid type.
`ListenerNotFoundError`	Raised if the listener that owns this service no longer exists. The agent construction path looks the listener up by ID and rejects registration against a listener that has been deleted.

Returns:

Type	Description
`Agent`	The registered agent object.

`deregister_agent_by_agent_id(agent_id)` ¶

Deregister an agent connected to this listener. This removes the agent from the system entirely.

Parameters:

Name	Type	Description	Default
`agent_id`	`str \| UUID`	The agent ID of the agent to deregister.	required

Raises:

Type	Description
`AgentNotFoundError`	Raised if the agent does not exist or is not connected to this listener.

`check_in_agent_by_agent_id(agent_id)` ¶

Check in an agent connected to this listener. This updates the agent's last check-in time and marks it as active.

Parameters:

Name	Type	Description	Default
`agent_id`	`str \| UUID`	The agent ID of the agent to check in.	required

Raises:

Type	Description
`AgentNotFoundError`	Raised if the agent does not exist or is not connected to this listener.

`get_next_task_message_by_task_id(agent_id, task_id, timeout=None)` `async` ¶

Get the next task message produced by a running capability for a specific task on an agent connected to this listener.

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, `None` if the timeout
`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 does not exist or is not connected to this listener.
`AgentTaskNotFoundError`	Raised if the task with the specified task ID is not found on the agent.

Note

Reading a task message counts as the agent making contact, so this performs an automatic check-in.

`get_next_task_message_sequential(agent_id, timeout=None)` `async` ¶

Get the next task message from the earliest running capability of an agent connected to this listener.

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 does not exist or is not connected to this listener.

Note

Reading a task message counts as the agent making contact, so this performs an automatic check-in.

`get_next_task_message_any(agent_id, timeout=None)` `async` ¶

Get the next task message from any running capability of an agent connected to this listener.

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 does not exist or is not connected to this listener.

Note

Reading a task message counts as the agent making contact, so this performs an automatic check-in.

`drain_task_messages_by_task_id(agent_id, task_id)` `async` ¶

Drain task messages from a specific running task of an agent connected to this listener 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 does not exist or is not connected to this listener.
`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 connected to this listener 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 does not exist or is not connected to this listener.

`drain_task_messages_any(agent_id)` `async` ¶

Drain task messages from any running capability of an agent connected to this listener.

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 does not exist or is not connected to this listener.

`dispatch_task_output_message(agent_id, task_output_message=None, task_id=None, success=None, message='', data=None, payload=None)` `async` ¶

Submit a result from an agent connected to this listener. This method validates that the task exists and is running, performs an automatic check-in, and submits the result.

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 submitting the result.	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 that this result corresponds to. Required when `task_output_message` is not given.	`None`
`success`	`bool \| None`	Whether the task was successful. Required when `task_output_message` is not given.	`None`
`message`	`str`	A message describing the result.	`''`
`data`	`dict[str, Any] \| None`	The result data.	`None`
`payload`	`Payload \| bytes \| bytearray \| None`	An optional binary payload associated with the result.	`None`

Raises:

Type	Description
`ValueError`	Raised if neither `task_output_message` nor both of `task_id` and `success` were given, so there is no result to submit.
`AgentNotFoundError`	Raised if the agent does not exist or is not connected to this listener.
`AgentTaskNotFoundError`	Raised if the task ID does not correspond to a running task for this agent.
`ValidationError`	Raised by pydantic if the dispatched output message fails model validation, for example when `data` holds values that are not JSON-serializable or `payload` is not a supported binary type.

`get_all_agents()` ¶

Get all agents connected to this listener.

Returns:

Type	Description
`list[Agent]`	A list of all agents connected to this listener.

`get_agent_by_agent_id(agent_id)` ¶

Get an agent by its agent ID, validating it is connected to this listener.

Parameters:

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

Raises:

Type	Description
`AgentNotFoundError`	Raised if the agent does not exist or is not connected to this listener.

Returns:

Type	Description
`Agent`	The agent with the specified agent ID.

Connected agents service¶

consortium.server.services.connected_agents_service ¶