Skip to main content

Shinkai Agents

In Shinkai, Agents are the individualized "AIs" that users interact with. Agents specifically:

  • Live underneath a single profile in a single Shinkai node
  • Own a Shinkai sub-identity
  • Connect to a specific LLM which it uses for all inferencing

As such, any AI Chat (job) that is ever created in a Shinkai node is always tied to a specific agent.

How To Add Agents

There are two methods to add agents into your Shinkai node to use for AI Chats.

Firstly, when initializing the node the on first boot, the user can specify zero or more agent to "pre-load" and include by default from the start. This requires using environment variables, which we'll touch on shortly.

Secondly, through Shinkai Visor users can add agents through a graphical interface easily by visiting the "Agents" section in the main menu. This approach is much easier to use, and allows you to easy browse the available options.

Using Node Configuration

When attempting to "pre-load" agents into your node, you will need to define environment variables that the node picks up on first boot. Specifically you need to define three things for each agent:

  • A custom name for the agent (which will become part of its sub-identity)
  • An internal shinkai name for the LLM model interface/model type
  • An api-key that will be used with the LLM interface

Let's take a look at some examples:


export INITIAL_AGENT_NAMES="mixtral"


export INITIAL_AGENT_NAMES="my_gpt,my_gpt_vision"

Agent Sub-Identities

As mentioned your agent will also register a sub-identity underneath your node which allows it to receive messages. Currently any of your client devices (under your profile) can send messages to your agents, with other nodes/identities over the global p2p Shinkai network coming in the future.

Every agent sub-identity matches the following standard:


Thus assuming you are running a node locally using @@localhost.shinkai, with a profile named main, these would be the sub-identities of your agent using the configs above:

  • mixtral: @@localhost.shinkai/main/agent/mixtral
  • GPT-4: @@localhost.shinkai/main/agent/my_gpt
  • GPT-4 Vision: @@localhost.shinkai/main/agent/my_gpt_vision