AgentManager

AgentManager is a utility to assist in spawning agents and keeping genome files in a centralized location.

This class also persists agent configuration information between instantiations, so that previously used genomes can be referenced from the genome store. Will automatically provide an AgentClient object when agent is spawned using manager.

Note

Requires access to the Docker Daemon running on the user’s computer, and access to Intelligent Artifact’s GAIuS Docker images.

Quickstart

from ia.gaius.manager import AgentManager

am = AgentManager()
am.kill_all_agents()
agent = am.start_agent(genome_file='simple.genome', agent_id='pvt', connect_jia=True, api_key='SECRET1234')
agent_client = agent.get_agent_client()

AgentManager

class ia.gaius.manager.AgentManager(genome_dir: Path | None = None, agents_dir: Path | None = None, thinkflux_dir: Path | None = None, comcom_dir: Path | None = None, local: bool = False)

Bases: object

__init__(genome_dir: Path | None = None, agents_dir: Path | None = None, thinkflux_dir: Path | None = None, comcom_dir: Path | None = None, local: bool = False)

Initialize AgentManager object (setup dirs, etc.)

This object can be used to spawn Agents using the start_agent() method.

add_genome(genome_file: dict)

add genome from provided filepath

Parameters:

genome_file (str) – genome file to add to AgentManager

Raises:

Exception – When genome not found

Returns:

contents of genome file

Return type:

dict

agent_context(genome_file: str = None, genome_name: str = None, user_id: str = 'jia', agent_id: str = '1', agent_name: str = None, connect_jia=True, api_key='ABCD-1234')

Provide ability to use Agent as a context manager. Internally calls start_agent and stop_agent.

Parameters:
  • genome_file (_type_, optional) – _description_. Defaults to None.

  • genome_name (_type_, optional) – _description_. Defaults to None.

  • user_id (str, optional) – _description_. Defaults to ‘jia’.

  • agent_id (str, optional) – _description_. Defaults to ‘1’.

  • agent_name (_type_, optional) – _description_. Defaults to None.

  • connect_jia (bool, optional) – _description_. Defaults to True.

  • api_key (str, optional) – _description_. Defaults to ‘ABCD-1234’.

Yields:

_type_ – _description_

delete_agent(agent_name)

Stop/Delete agent & remove config file from agents_dir

Parameters:

agent_name (str) – name of agent to stop

Returns:

string depicting deletion status

Return type:

str

delete_comcom(name: str)
delete_genome(genome_name)

Delete genome from centralized genome_dir

Parameters:

genome_name (str) – genome name to delete

delete_tf(tf_name: str)

Kill a Thinkflux container using it’s tf_name attribute

Parameters:

tf_name (str) – attribute passed when spawning Thinkflux

Raises:

Exception – When config not found

get_all_agent_status()

Get the status of all agents in current_agents dict

Returns:

{ agent_name : alive? }

Return type:

dict

get_genome(genome_name)

Get genome by name, return as dict

Parameters:

genome_name (str) – filename for genome in genome_dir

Raises:

Exception – When genome not found

Returns:

contents of genome file

Return type:

dict

kill_all_agents(update=True)

Kill all agents known to AgentManager

Parameters:

update (bool, optional) – Whether to update AgentManager information before killing containers. Defaults to True.

list_genomes()

List the genomes present in the localized genome store

Returns:

list of genome files

Return type:

list

remediate_dead_agents()

Remove all agents that cannot be pinged.

start_agent(genome_file=None, genome_name=None, user_id: str = 'jia', agent_id: str = '1', agent_name=None, connect_jia=True, api_key='ABCD-1234', single_container=False, **kwargs) AgentInfo

Spawn an agent and save its information in the localized agents dir

Note

If you wish to use a genome that has not been used by the AgentManager before, pass it in the genome_file field. This will retrieve the genome from the specified path, and save it in the localized genome dir for future use.

Parameters:
  • genome_file (str, optional) – Path to outside genome file. Defaults to None.

  • genome_name (str, optional) – Name of genome in the localized genome dir. Defaults to None.

  • user_id (str, optional) – user id for naming docker containers. Defaults to ‘jia’.

  • agent_id (str, optional) – agent id for naming docker containers. Defaults to ‘1’.

  • agent_name (_type_, optional) – descriptive name “alias” for agent. Defaults to None.

  • connect_jia (bool, optional) – Whether to attempt to connect agent to Jia docker container. Defaults to True.

  • api_key (str, optional) – Control the api key used to access agent. Defaults to ‘ABCD-1234’.

Raises:

Exception – If there is a conflicting agent with user_id and agent_id already present/alive

Returns:

AgentInfo object corresponding to started agent. can be used to retrieve AgentClient object using AgentInfo.get_agent_client()

Return type:

AgentInfo

start_comcom(name: str, api_key: str, docker_image: str, port: int = 8081, comcom_id: str = '1', agents_to_connect: list | None = None, additional_ports: Dict[str, int] = {}, volumes: dict | None = None) ComcomInfo
start_hoster()

Start dvdarias/docker-hoster docker container to resolve container hostnames into IP addresses. More friendly for AgentManager usage

start_tf(tf_name: str, api_key: str, docker_image: str, port: int = 8090, user_id: str = 'tf', tf_id: str = '1', environment: dict | None = None, privileged: bool | None = None, volumes: dict | None = None, agents_to_connect: list | None = None) TFInfo

Spawn a Thinkflux container using provided config. Store config in AgentManager

Container name is defined as:

“tf-{user_id}-{tf_id}”

Parameters:
  • tf_name (str) – descriptive name “alias” for Thinkflux

  • api_key (str) – Passed as API_KEY env variable to container

  • docker_image (str) – Container image to spawn. E.g. “registry.digitalocean.com/intelligent-artifacts/thinkflux:develop”

  • port (int, optional) – _description_. Defaults to 8090.

  • user_id (str, optional) – user_id portion of container extension. Defaults to ‘tf’.

  • tf_id (str, optional) – tf_id portion of container extension. Defaults to ‘1’.

  • environment (dict, optional) – additional environment variables to provide to container, as key-value pairs. Defaults to None.

  • privileged (bool, optional) – run container in privileged mode. Defaults to None.

  • volumes (dict, optional) – volumes to mount in container as key-value pairs. Defaults to None.

  • agents_to_connect (list, optional) – list of agents to connect to Thinkflux. Defaults to None.

Raises:
  • Exception – If invalid agents passed in agents_to_connect

  • Exception – If tf_name already exists in AgentManager

  • Exception – If a thinkflux with user_id and tf_id already exists in AgentManager

Returns:

Object corresponding to spawned Thinkflux

Return type:

TFInfo

stop_hoster()

Stop dvdarias/docker-hoster docker container

update_current_agents()

Update AgentManager’s list of configured agents, thinkflux, comcom, genomes

AgentInfo

class ia.gaius.manager.AgentInfo(user_id: str, agent_id: str, agent_name: str, genome_name: str | None = None, genome_file: str | None = None, agent_config=None, location: str = 'local', LOG_LEVEL=20, api_key='ABCD-1234', genome_dir=None, agents_dir=None, genome=None, single_container: bool = False, local_agent_config=None, version='latest', **kwargs)

Bases: object

__init__(user_id: str, agent_id: str, agent_name: str, genome_name: str | None = None, genome_file: str | None = None, agent_config=None, location: str = 'local', LOG_LEVEL=20, api_key='ABCD-1234', genome_dir=None, agents_dir=None, genome=None, single_container: bool = False, local_agent_config=None, version='latest', **kwargs)

Wrapper class for Agent information. Used to start/stop agents, and save config information to a central location

Parameters:
  • user_id (str) – User id attached to docker contaienrs spawned using AgentInfo

  • agent_id (str) – Agent id attached to docker containers spawned using AgentInfo

  • agent_name (str) – Descriptive, user-friendly name to refer to agent by

  • genome_name (str, optional) – If genome already in centralized location, refer to it by its name

  • genome_file (str, optional) – To copy outside genome into genome store, provide filepath here

  • agent_config (_type_, optional) – Stores AgentConfig details once agent is spawned.

  • location (str, optional) – In future will support spawning at several locations (local, private cloud, DigitalOcean, etc). Defaults to ‘local’.

  • LOG_LEVEL (logging.LEVEL, optional) – Used to control verbosity of messages in agent spawn script. Defaults to logging.INFO.

  • api_key (str, optional) – Used to set API KEY of spawned agent. Defaults to “ABCD-1234”

check_running()

Check if we can access the agent

Returns:

True for success, False for failure

Return type:

bool

connect_jia()

Connect agent to jia (add jia to the agent’s network)

delete_config_file()

Kill agent and delete config information from agents directory

classmethod fromFile(filepath: str | Path)

Construct AgentInfo object from file

Parameters:

filepath (str) – path to file to load

Returns:

AgentInfo object created from the file

Return type:

AgentInfo

classmethod fromJSON(json_obj)

Construct AgentInfo from JSON object

Parameters:

json_obj (dict) – Contains fields necessary for constructing AgentInfo

Returns:

AgentInfo object created from JSON object

Return type:

AgentInfo

get_agent_client(local: bool = False)

Retreive AgentClient object from started agent

Returns:

ia.gaius.agent_client.AgentClient

get_docker_networks()

Get names of networks this agent is a part of (uses gaius-api-{user_id}-{agent_id})

Raises:

Exception – More that one container found with same name

Returns:

list of networks

Return type:

_type_

kill_agent()

Attempt to kill a running agent

save_config_file()

Store config information for agent in agents directory, based on agent name

spawn(connect_jia=True)

Start a new agent using information provided in constructor

Parameters:

api_key (str, optional) – API Key for agent. Defaults to “ABCD-1234”.

toJSON()

Dump config information to a JSON object (dict)

Returns:

config information

Return type:

dict

TFInfo

class ia.gaius.manager.TFInfo(user_id: str, tf_id: str, tf_name: str, location: str, api_key: str, thinkflux_dir: str, docker_image: str, port: int, privileged: bool = False, environment: dict | None = None, volumes: dict | None = None, **kwargs)

Bases: object

__init__(user_id: str, tf_id: str, tf_name: str, location: str, api_key: str, thinkflux_dir: str, docker_image: str, port: int, privileged: bool = False, environment: dict | None = None, volumes: dict | None = None, **kwargs) None
connect_agents(agents: List[AgentInfo])
delete_config_file()

delete config information from agents directory

classmethod fromFile(filepath: str | Path)

Construct AgentInfo object from file

Parameters:

filepath (str) – path to file to load

Returns:

AgentInfo object created from the file

Return type:

AgentInfo

classmethod fromJSON(json_obj)

Construct AgentInfo from JSON object

Parameters:

json_obj (dict) – Contains fields necessary for constructing AgentInfo

Returns:

AgentInfo object created from JSON object

Return type:

AgentInfo

kill()
save_config_file()

Store config information for agent in agents directory, based on agent name

spawn() bool
toJSON()

Dump config information to a JSON Object

Returns:

config information

Return type:

dict