Quickstart

Introduction

Instrukt is terminal-based environment for prototyping and using AI agents. It provides a chat-like interface serving as a prompt and command line REPL at the same time, helping you conveniently develop, instruct, and debug your AI agents.

Instrukt features a simple interface and library for creating agents, indexes and tools.

By default, Instrukt features a Q&A agent that is tailored for conversations with question/answering over document indexes.

Patreon supporters have access to the alpha version of Docker Isolated Agents. It provides a safe, sandboxed environment for agents to perform their tasks on any existing container or image.

Instrukt was designed to allow you create custom workflows with quick feedback loops. The inbuilt debug shell ctrl+d gives you access to a live IPython console in the running app namespace. Use it to introspect and debug agents and tools.

Custom Agents

Instrukt agents are simple python packages stored under the path $HOME/.local/share/instrukt/agents.

You can create your own agents and share them with others. You can also set a custom path in the configuration file ~/.config/instrukt/instrukt.yml.

Creating a custom agent

To define a custom agent you need to:

  1. Setup a python package under the configured path. (don’t forget the init.py file)

  2. Create a manifest.json:

The manifest file must define the following:

  • name: the name of the agent without spaces. Must be same as the package name.

  • description: a description that will be displayed in the agents selection menu.

  • version

  1. Create an entry point named main.py

You must create a class that implements the InstruktAgent base class.

Take a look at the builtin agents demo and chat_qa found in the source code under instrukt/agent_modules for examples of how to create your own.

User Interface

The interface is divided in 3 main panes:

  • the console: left pane

  • the agent output: right pane

  • the prompt-repl input: bottom

Console Pane

The left pane serves as the main console for the app. It displays the output of system REPL commands that start with . or /.

Prompt Input

This is where you interact with the AI agents and app. It provides a prompt where you can input queries and instructions for the agents to execute. Additionally, the prompt serves as a command line REPL to interact with the Instrukt environment.

Editing with an external editor

When the prompt input is focused you can spawn an external editor to edit the input with ctrl-e.

If the environment variable EDITOR is set, it will be used, otherwise vim is used.

Monitor Pane

The right pane is dedicated the agent output alongside the user messages.

Agent Output

The agent output window shows the thought process and the final output of the AI agents. It displays the conversation with agents and provides a detailed view of the agent’s activities.

Realm Window

This is an optional component that will be shown for agents using a certain tools such as sandbox environment. For docker isolated agents, this window shows the live terminal where the agent is attached to and displays the input sent by the agent and output from the container.

Index Management

The index management window allows you to manage your collections of documents that can be used by agents for question-answering scenarios.

Indexes are used to provide more context to the agent. You can create indexes and attach them to active agents at any time.

FAQ

Terminal Colors

If the colors seem off make sure to:

  • Try to set the TERM=xterm-256color.

  • Try on a different and modern terminal.

  • Make sure your terminal that supports 256 color palette.

Select And Copy

Copy Agent Replies

Click on a reply from an agent to copy its content to the clipboard. Make sure to install a clipboard utility like xsel or xclip if you’re on Linux.

Terminal Select/Copy

Running a Textual app puts your terminal in to application mode which disables clicking and dragging to select text. Most terminal emulators offer a modifier key which you can hold while you click and drag to restore the behavior you may expect from the command line. The exact modifier key depends on the terminal and platform you are running on.

  • iTerm Hold the OPTION key.

  • Gnome Terminal Hold the SHIFT key.

  • Windows Terminal Hold the SHIFT key.

Refer to the documentation for your terminal emulator, if it is not listed above.

Nerdfonts Icons

You can activate nerdfont icons for a compact interface by setting the appropriate setting in: ~/.config/instrukt/instrukt.yml:

interface:
  nerd_fonts: true

Debug mode

You can quickly activate debug mode with the command %debug in the prompt.

Currently mostly useful for index creation, it will enable more verbose output in the index management log console.