Create your first Agent

The first Agent is already created, his temporary name is phantom. You can find it in the agents folder.

Firstly, rename phantom.py to fit your script or action purpose, for instance my-parser.py.

mv agents/phantom.py agents/my-parser.py

info

An Agent is a python script with a Class, describing the Agent metadata and mission.

We will go through my-parser.py file in this tutorial, part by part.

Here is the final modified sample of the my-parser.py file for the Agent my-parser.

agents/my-parser.py

from ..base import Base, logger

class MyParserAgent(Base):
    NAME = "MyParser"
    ACTIVATED = True
    VERSION = "1.0"
    MISSION = "Yet another parser to parse"

    def mission(self):
        logger.info(f'[{self.NAME}] Checking in.')
        # MISSION GOES HERE
        return <your-output>

Class

An Agent is a Class. For its name, I usually go with the Agent name followed by Agent, e.g. my-parser becomes MyParserAgent.
You can name your Classes as you see fit.

class MyParserAgent(Base):

Metadata

The Agent Class features various metadata (attributes), used to identify and describe him.

tip

You can add your own attributes to your Agent, follow the guide Agent Metadata.

By default, an Agent has 4 attributes, specified in the file base.py.

• NAME: Agent Name
• ACTIVATED: Whether this agent is enabled or not, False by default
• VERSION: Version, used for Agent versionning
• MISSION: Short description for its mission, its usage

Every Agent inherits the attributes of the Base Class. You can override these attributes by redefining them within the Agent Class.

class MyParserAgent(Base):
    NAME = "MyParser"
    ACTIVATED = True
    VERSION = "1.0"
    MISSION = "Yet another parser to parse awesome stuff"

warning

By default Captain uses a file path as input parameter (-f FILE) tu run Agents on.
In this example, to simplify, we are not using it. Please see Agent Input to see how to retrieve the argument in the agent.

Mission

The mission is the core of every Agent. It represents their functionality.
Your script (in this case the parser intelligence) should therefore go in this function.

def mission(self):
    logger.info(f'[{self.NAME}] Checking in.')
    # AGENT MISSION GOES HERE
    return <your-output>

This is up to you whether you want to return something (maybe to write to an output file) or just a boolean as a status to illustrate the correct execution.

Your agent is now ready to do its mission, you can quick ly check it using the captain agents command.

In the next section we are going to tailor Agents.