AFK is a fully features autonomous data platform for non technical people - an agentic chatbot that can answer complex questions, perform tasks and generate reports.
At its core, AFK is just an agentic llm streamlit client app with mcp integration and an ipython environment. We give an LLM a set of mcp servers to connect to, multiple agents to act as and a running ipython environment (with each agent getting its own storage and session).
This, combined with us taking non-thinking models and prompting them into thinking ones using <chain-of-thought> process turns into a powerful data platform.
AFK is comprised of multiple agents that converse with each other, delegate tasks to one another and produce a joined output based on the CAP protocol.
Based on the CAP protocol, each agent can message any of the other running agents and provide them with extra context. Also, each agent's spec details which agents an agent can delegate tasks to. Besides whats detailed in the CAP protocol and agents spec, each of the agents lives inside an ipython environment, with his own storage and file system thats separated from other agents. Also, each agent has access to its own tools based on his permissions in his agent CAP spec, as well as the capability to use functions.
Each agent can freely execute python code through the ipython environment and receive the output back. This includes saving or reading files from its secluded ipython storage space, as well as using the tools it has access to (more on that later).
This can be done using the <|python_tag|>.
An agent has access to both tools and functions. Both of these mean actions that an agent can perform, but, they have their differences.
In general, though, here's a comparison table:
| Aspect | Tool | Function |
|---|---|---|
| Under the Hood | mcp servers, local or remote | client side, predefined functions |
| Way to Call | Inside a python execution block, using the <|python_tag|> tag, like a regular python function. |
Regular, model specific function call. |
| Purpose | Performing actions that need to be evaluated for reflection / analysis / manipulated with code (getting information, posting information, invoking things...) | User viewable, client side outputs. Either for viewing or for getting the user's input. |
| Moderated | Yes, based on the agent CAP spec, with an extra optional user permission per tool | No |
Tools are actually mcp servers, whether local or remote. These are actions that need to be evaluated and return an output, and the user will usually not ever see them running or their raw output without it going through an agent first. The most important distinction between tools and functions though, is the fact that tools are called from inside the ipython environment that the agent has, just like calling any other python function. This allows the agent to manipulate the output of tools through code, send multiple tool calls at once etc... Also, tools can be moderated using the agent CAP spec, with some requiring an additional user permission before being run.
An example for some tools could be:
- query_sql: A tool that allows the agent to query an sql database, and returns the result as a pandas df.
- search_emails: A tool that allows the agent to filter through the user's emails, and returns them as a json list.
- send_emails: A tool that allows the agent to send emails through the user's account (NOTICE - this tool, for example, could require an extra user permission).
Functions are not mcp servers, but instead they're just client-side functions. These don't run through the ipython environment, and are not moderated at all. While these aren't called from the ipython environment, they can still use outputs and variables from it in their parameters. These usually have something to do with showing something to the user on the client, or getting his input.
Examples for some functions could be:
- get_date_range: Pops up a calendar on the client and waits for the user to select a date range.
- show_map: Shows a map in the client with, for example, some geopandas data from a previous code execution or tool call.
- show_ipython_output: Shows the ipython figure output of a previous execution.
We currently have 3 different agent roles. All of them powered by CAP: PM, Data Analyst and QA.
The pm is the first to be called on a user request. Its job is to drill down on the user message, clarifying it until there are no vague parts and the outputs we expect are fully clear. The pm must know the business world of the question extremely well, and also understand what the user actually wants, as opposed to what he requests for.
For example, lets say the user asks for general sales trends in the last quarter. This question is really vague, and we can answer it in a lot of different ways. The PM's job is now to list and understand all of those ways, and to fully understand what the user expects to see, what could be helpful for him to see, and drill down on what things trends actually mean.
He may research company events using tools, and drive further analysis questions using them. He may ask the user some questions back...
At the end, before he delegates the question to another agent, he fully mapped out everything he wants answered to craft his response to the user.
The Data Analyst is responsible for researching, analyzing and providing insights. It uses the in depth mission instructions he gets from the pm, and based on those tries to answer the question and provide a full, comprehensive report. He always critiques and doubts his findings (hypothesis 0) and uses While the PM breaks the user's question into clear, nuance free and easy to follow tasks that must be answered. The analyst answers them and can provide further insights based on his previous findings. He can also talk back and forth with the user / pm. At the end, the analyst provides a well written answer, which he then delegates to the QA for quality assurance, and to the PM to make sure they actual question the user has asked was answered.
The QA usually receives the final report/answer the analyst has worked on. Then, he critics it, tests all of the findings of the analyst and makes sure they're all correct. He always tries to think of alternative calculations / code to test the findings of the analyst (as simply running exactly the same code of his will result in the same answer). He also goes beyond just testing code, he tests the findings themselves, makes sure they're logical and that they make sense. If anything doesn't make sense, he passes it back to the analyst, awaiting his fixes to test again, and then passes it to the pm. He generally works on the finished products of the analyst, but can receive anything from any agent.
AFK is designed to work with any model type, including non thinking models. If our model is not a thinking model, we'll have to "prompt" it into being one, using our chain-of-thought protocol. The protocol instructions are detailed in the chain-of-prompt markdown guide.
Users sometime speak a different language than english, they may wish to query AFK and consume the output in their own native language. While LLMS are great at translating text, their overall intelligence may drop if we force them to perform the whole chain-of-thought process + multi agent exchanges entirely in that language.
For that purpose, AFK provides an optional translation layer. This layer takes the native language user inputs and translates them to english for the whole thought process to occur in. Then, any textual user facing output (whether its agent messages to the user or the final responses) also get translated back into the native user language.
This translation layer, if activated, works passively to make sure the responses, if needed, are translated between the languages. This means the user doesn't have to set a specific language and can even switch them as he talks. All we have to do is activate this layer, as it is disabled by default.
Inside the docs folder, there's a plethora of documentation files gathered for additional information.
-
custom_agent_protocol contains the specification and documentation on CAP, our internal custom agent protocol.
-
The mcp docs folder contains documentation content from the official mcp documentation website, and details in depth the entire protocol. Inside this folder we have:
- files - The full documentation broken down into folders and files.
- full_doc - The full website documentation in one single file - this is good if you wish to search or just read it whole.
- python_sdk - The readme doc file for the official mcp python sdk.
For testing, use pytest. Tests are written inside the tests directory.
Install dependencies, set your Groq API key, and then run the Streamlit application from the repository root:
pip install -r requirements.txt
cp .env.example .env # edit this file with your GROQ_API_KEY
streamlit run afk/main.pymain.py modifies sys.path so it can be executed directly, but it still needs
to be run from the repository root to resolve imports properly. The app
launches at http://localhost:8501.