Define Your Agent with a JSON Configuration

This guide walks you through creating an AI agent by manually defining its structure in a JSON file and uploading it to Handit.AI. This method is ideal for developers or teams looking for more control, flexibility, and easy versioning of their agents.

Why Use JSON Configuration?

Using a JSON file allows you to:

• Define complex agent logic programmatically

• Store and track agent versions in Git or any version control system

• Dynamically generate agents as part of your pipeline or tooling

Defining your Agent in JSON

Create a JSON file that represents your agent and its structure. We recommend using the structure below as a starting point. However, a strict format is not required — Handit.AI uses AI to normalize and extract your configuration, even if it varies slightly.

{
  "agent": {
    "name": "Your Agent Name",
    "slug": "your-agent-slug",
    "description": "Description of what your agent does"
  },
  "nodes": [
    {
      "name": "Node Name",
      "slug": "node-slug",
      "description": "Description of what this node does",
      "type": "model",
      "problem_type": "text-generation",
      "next_nodes": ["next-node-slug"]
    }
  ]
}

📝 You can define as many nodes as needed. Nodes can be models or tools, and you can define flow logic using the next_nodes field.

Upload Your Configuration on Handit

1. Log in to your Handit.AI account.

2. Go to the "Agents" section from the sidebar.

3. Click the "Upload Agent JSON" button.

4. Select your JSON configuration file from your computer.

5. Wait a few moments — your agent will appear in the Agents list once it's been processed successfully.

Your agent is now live and ready to be integrated into your project!

Next Steps

1. Code Integration - Learn how to integrate your agent with your code
2. Best Practices - Review best practices for agent creation