In this quickstart, you’ll learn to build your first Modus App with a single function that demonstrates how to integrate external APIs with AI models. We’ll start with this stateless function, and later you can learn about building stateful agents that maintain memory and coordinate complex operations.

Our examples use Go, which we recommend for new projects. You can also choose AssemblyScript if you prefer. For AssemblyScript usage, refer to the AssemblyScript SDK overview.

​
Prerequisites

  • Node.js - v22 or higher
  • Text editor - we recommend VS Code
  • Terminal - access Modus through a command-line interface (CLI)

​
Building your first Modus app

1

Install the Modus CLI

Install the Modus CLI to manage your Modus applications.

npm install -g @hypermode/modus-cli
2

Create a new app

Create your first Modus app.

modus new

Choose between Go and AssemblyScript. Both compile to WebAssembly for fast performance.

3

Run your app locally

Start your local development server:

modus dev

This starts your app and provides a URL to access the API.

4

Add external connections

To connect to external services, add this to your modus.json:

modus.json
{
  "connections": {
    "zenquotes": {
      "type": "http",
      "baseUrl": "https://zenquotes.io/"
    }
  }
}
5

Add an AI model

Add an AI model to your manifest:

{
  "models": {
    "text-generator": {
      "sourceModel": "meta-llama/Llama-3.2-3B-Instruct",
      "provider": "hugging-face",
      "connection": "hypermode"
    }
  }
}
6

Set up model access

Install and authenticate with the Hyp CLI to access Hypermode-hosted models:

  npm install -g @hypermode/hyp-cli

Authenticate with your Hypermode account:

  hyp login

This connects your local development environment to Hypermode’s model infrastructure.

7

Create your first function

Create a function that fetches data from an external API and uses AI for analysis:

Create intelligence.go:

intelligence.go
package main

import (
  "errors"
  "fmt"
  "strings"

  "github.com/hypermodeinc/modus/sdk/go/pkg/http"
  "github.com/hypermodeinc/modus/sdk/go/pkg/models"
  "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
)

type IntelReport struct {
  Quote   string `json:"quote"`
  Author  string `json:"author"`
  Analysis string `json:"analysis,omitempty"`
}

const modelName = "text-generator"

// Fetch a random quote and provide AI analysis
func GatherIntelligence() (*IntelReport, error) {
  request := http.NewRequest("https://zenquotes.io/api/random")

  response, err := http.Fetch(request)
  if err != nil {
    return nil, err
  }
  if !response.Ok() {
    return nil, fmt.Errorf("request failed: %d %s", response.Status, response.StatusText)
  }

  // Parse the API response
  var quotes []IntelReport
  response.JSON(&quotes)
  if len(quotes) == 0 {
    return nil, errors.New("no data received")
  }

  // Get the quote
  intel := quotes[0]

  // Generate AI analysis
  analysis, err := analyzeIntelligence(intel.Quote, intel.Author)
  if err != nil {
    fmt.Printf("AI analysis failed for %s: %v\n", intel.Author, err)
    intel.Analysis = "Analysis unavailable"
  } else {
    intel.Analysis = analysis
  }

  return &intel, nil
}

// Use AI to analyze the quote
func analyzeIntelligence(quote, author string) (string, error) {
  model, err := models.GetModel[openai.ChatModel](modelName)
  if err != nil {
    return "", err
  }

  prompt := `You are an analyst.
  Provide a brief insight that captures the core meaning
  and practical application of this wisdom in 1-2 sentences.`
  content := fmt.Sprintf("Quote: \"%s\" - %s", quote, author)

  input, err := model.CreateInput(
    openai.NewSystemMessage(prompt),
    openai.NewUserMessage(content),
  )
  if err != nil {
    return "", err
  }

  input.Temperature = 0.7

  output, err := model.Invoke(input)
  if err != nil {
    return "", err
  }

  return strings.TrimSpace(output.Choices[0].Message.Content), nil
}
8

Test your function

Restart your development server:

modus dev

Modus automatically generates a GraphQL API from your functions. Since your function is named GatherIntelligence(), it becomes a GraphQL query field called gatherIntelligence.

Open the Modus API Explorer at http://localhost:8686/explorer to test your function. The explorer is fully GraphQL-compatible, so you can issue this query:

query {
  gatherIntelligence {
    quote
    author
    analysis
  }
}

You’ll receive a response like:

{
  "data": {
    "gatherIntelligence": {
      "quote": "The only way to do great work is to love what you do.",
      "author": "Steve Jobs",
      "analysis": "
        This emphasizes that passion and genuine interest in your work are fundamental drivers of excellence.
        When you love what you do, the effort required for mastery feels less burdensome and innovation flows more naturally.
      "
    }
  }
}

Your function now:

  • Fetches data from external APIs
  • Uses AI models for analysis
  • Provides intelligent responses
  • Handles errors gracefully
9

Monitor AI calls

When running locally, Modus records every AI model call for monitoring and debugging. You can see this in the Modus explorer.

Local inference tracking is supported on Linux and macOS. Windows support is incoming.

You can monitor:

  • Requests sent to AI models
  • Response times and token usage
  • Model performance metrics
  • Error rates and debugging info

​
What’s next?

You’ve successfully built your first Modus function. But this is just the beginning. Real agents maintain memory, coordinate complex operations, and never lose their context.

Ready to upgrade from simple functions to stateful agents? Check out What’s an Agent? to learn how to build persistent, memory-enabled agents that remember every interaction and can coordinate sophisticated multi-step operations.

For more mission templates and advanced operations, explore the Modus recipes.