🚀 How to Build Your First Agent on Johan.Chat: A Quick Guide for Beginners

If you’re new to Johan.Chat and want to build your first agent quickly, this guide will help you get started. Johan is a low-code platform based on the concept of Agents as Code (AaC), allowing you to create intelligent, conversational agents with minimal code — and maximum flexibility.

🧱 1. Creating Your First Agent

After creating a new agent on the Home screen, you’ll be taken to the Studio, where you can configure the agent’s context, behavior, and tools.

🧠 2. Understanding the Studio

Inside the Studio, you’ll find several tabs that define how your agent thinks and behaves.

🔹 Context

Write a brief, generic description of your agent’s role. This helps the model understand what the agent is generally supposed to do.

🔹 Instructions

A list of imperative statements that act like behavioral rules. Example: Always answer using the most recent data available.

🔹 Behavior

This is where you write the “system prompt” — a more detailed set of instructions or persona behavior. Supports Markdown.

🔹 Notes

Short context blocks triggered based on input similarity. Each note includes a title and text. This helps keep the agent’s context focused and clean.

💡 Tip: Use Notes for modular, relevant context that doesn’t need to be always active. Proper separation between Context, Instructions, Behavior, and Notes greatly improves agent performance.

🧰 3. The Tools Tab

Your agent’s capabilities live here. There are two types:

✅ Custom Functions

Custom low-code actions you create using JavaScript. Great for calling APIs, triggering logic, or returning dynamic data.

🧩 Plugins

More advanced features built via CLI — only available to companies with a commercial license.

🧑‍💻 4. Creating a Custom Function (Tool)

To build a new function:

1. Name: Unique name for the tool.
2. Description: This tells the agent when to use the tool. Example: "Fetch user's balance" — the agent will learn to call this when the user asks for their balance.
3. Parameters: Optional inputs (name, type, description, and required flag).
4. Code: JavaScript logic using Johan’s standard structure.

🧬 Default Code Structure

const { user, agent } = args;

// Your function logic here

return { message: "" };

• user and agent are provided automatically.
• Any custom parameters you define will also appear in the args object.

📦 Example: Static Response (Basic)

const { user, agent } = args;

return fetch('https://api.yourdomain.com/balance')
  .then(response => {
    if (!response.ok) throw new Error('Request Error');
    return response.json();
  })
  .then(data => {
    return { message: `Your balance is $ ${data.balance}` };
  })
  .catch(error => {
    return { message: `Unable to fetch balance. Please try again later.` };
  });

🔁 Example: Dynamic Response with system and continue

If you want a more intelligent, multi-turn reply, use system and continue.

const { user, agent } = args;

return fetch('https://api.yourdomain.com/balance')
  .then(response => {
    if (!response.ok) throw new Error('Request Error');
    return response.json();
  })
  .then(data => {
    return {
      message: `Let me check your balance...`,
      system: JSON.stringify(data),
      continue: true
    };
  })
  .catch(error => {
    return { message: `Unable to fetch balance. Please try again later.` };
  });

In this case, the agent receives the data via system and continues the conversation based on it.

✅ Best Practices

• Avoid await — use .then() and .catch() for safe execution inside tools.
• Always return an object with at least a message key (even if empty).
• Use system + continue for contextual, dynamic conversations.
• Use descriptive tool names and parameter definitions to guide the agent’s reasoning.

🎯 Conclusion

Johan.Chat makes building conversational agents intuitive and scalable. Its low-code approach and powerful context tools allow you to go from idea to implementation in minutes. Today, you learned how to build your first agent and write your first custom function.

✨ In the next posts, we’ll explore advanced topics like sending images, uploading documents, and using plugins for more robust integrations.