What are agents?

In the simplest form possible, an agent is a headless instance of a CLI with specific instructions that gives it a role and goals. The agent is temporarily spawned to achieve its goal and then destroyed. Which helps keep its context clean and focused only on what it needs to achieve its objectives.

How to create an agent?

Creating an agent is pretty simple. There are two ways to create an agent:

1. Click on the “Create” button next to the Library header in the Agents List pane. This will create an agent using Jarvix’s template and calls it myagent.md
2. Click on Menu > Open agents folder which will open the folder where all your agents are located. You can also navigate to it using your file system. Create an empty .md file and give it a name such as myagent.md

Either way is fine, as long as the agents you create manually follows the structure of a proper agent file.

Note that we recommend using the “Create” button in the Agents List pane so it generates a boilerplate agent and you edit it. That way the structure matches exactly what Jarvix expects.

Anatomy of agent

While agent files are regular .md files, they have a certain structure that need to be followed or you risk Jarvix not recognizing it and your pipeline not functioning correctly.

As seen below the agent file is divided into two main section. A YAML front matter (top part and is highlighted in the template) and the bottom part which we refer to as the agent’s definition.

YAML front matter

Think of this as the configuration of your agent so Jarvix understands what sort of agent is this. We’ll explore each field individually.

• id; each agent in Jarvix has its own uique ID. This is a field that is generated by Jarvix to identify which agent is which. It is generated at run time (i.e. when you load the agent into a project) once. This means that an agent will have the same UUID across all projects. It follows a certain format that Jarvix expects so using your own may break it.

Note that changing this field may result into unexpected results. It is better to not touch this field unless you absolutely know what you’re doing.

• name; this is the display name of the agent. The one you see in the Pipeline Graph and the Agents List pane.
• reads; this is a list of files that you want this agent to read before it takes any action. For example, if this is a programmer agent, then you’d probably need it to reach what the architect agent did to understand the architecture and tech stack of the artifact it is creating. That said, you’d also need it to also read the programmer reviewer agent so it can fix its own mistakes when looping back from a reviewer agent.
• review_target; if this is a reviewer agent (an agent that reviews other agent’s output) then this field should be set to the target agent’s unique ID (the one being reviewd).
• loop; this field is not set and it defines the looping settings for a reviewer agent.
• loop.type; if this is a reviewer agent, this field identifies what kind of loop will the agent execute. In Jarvix, a reviewer agent can have one of two loop types: revision and iteration. Revision indicates that there is a limit to the number of times the reviewer agent will review the target’s work and send it back to be modified. Iteration indicatest that there is no limit to the number of times the reviewer agent will review the target’s work.
• loop.max_revision_loops; this is the maximum number of cycles or loops the revision agent will send the work back to its target.
• timeout_seconds; this is a timer that is set for each agent with a default value of 300. If the agent exceeds this time active and haven’t finished work yet, Jarvix will auto-kill that agent. This is to prevent agents from hanging forever and no way to kill them outside of killing their process.

Note that for producer agents (agents that will create artifacts such as a programmer) we recommend increasing that to 600 or above depending on the size of the project.

• allowedCommands; by default this is empty for all agents. You can modify this field by inserting commands you know the agent will need to finish their objectives.
• excludedCommands; by default this is empty for all agents and gets filled by Jarvix on launch to prevent agents from using potential destructive commands.

Agent definition:

The agent definition is a free form text that uses standard markdown format. It defines what the agent is and what it does. You can write here whatever you want and structure it the way you want. This part gets injected into the agent when launching as part of its context to understand what it is and what is expected of it.

Importing agents:

Since Jarvix is flexible, you can use any .md agent files that you can find online or even non .md if you do two things:

1. If the agent file isn’t in .md format, change it to .md format.
2. Add the YAML front matter at the top with the relevant fields set appropriately.

Note that some agents you find online may contain harmful behaviour and may lead to unwanted results. Jarvix will try to help (by blocking certain commands), but it can not eliminate such threats completely. It is your responsibility to double check and make sure that any agent files you use are completely safe and unharmful.

Go back to the welcome page