Basic Tutorial

In this section, we’ll walk through building a more sophisticated Agentlang application: a complete blogging service. This example will show how entities, relationships, workflows, and agents can work together in a real-world scenario.

To get started, let’s create a new project and move into its directory:


agent init blog
cd blog

These steps set up the foundational project structure, allowing you to organize your modules, define your schema, and begin implementing workflows and agents for your blogging service.

Defining the Post Entity

We’ll begin by modeling the central piece of our blogging service: the Post. In Agentlang, an entity represents a persistent piece of data that the system can store, query, and relate to other entities.

A simple Post entity might include attributes like id, title, content, and createdAt. Here’s how you can define it:

src/core.al


module blog.core
  
entity Post {
    id UUID @id @default(uuid()),
    title String,
    content String,
    postedBy Email,
    createdAt DateTime @default(now())
}

Explanation of attributes:

id: A unique identifier for each post. We use UUID with @default(uuid()) to automatically generate a new ID.
title: The title of the post as a string.
content: The main body of the post.
postedBy: The email of the author.
createdAt: The timestamp when the post was created. Using @default(now()), the system sets it automatically.

With this definition, you now have a fully functional Post entity that can be persisted to the database.

Accessing the `Post` Entity Over HTTP

Now that we have our Post entity defined, let’s see how to interact with it using HTTP requests. One of the great things about Agentlang is that it automatically exposes a RESTful API for each entity in your application — so you don’t need to write any server code.

1. Start the Blog Service

First, start the Agentlang runtime:


agent run

Your blog service will now be listening for incoming HTTP requests on port 8080.

2. Creating a Blog Post

Let’s create our first blog post. Open a terminal and run the following curl command:


curl -X POST http://localhost:8080/blog.core/Post \
  -H 'Content-Type: application/json' \
  -d '{"title": "Hello world", "content": "This is my first post", "postedBy": "mm@fractl.io"}'

What just happened? The runtime automatically mapped your Post entity to a REST endpoint. By sending a POST request with JSON data, we created and saved a new blog post in the system. Agentlang even fills in system-generated fields, like the creation timestamp and id.

3. Fetching the Blog Post

To check that the post was saved, we can fetch it by its id, using a GET request:


curl -X GET http://localhost:8080/blog.core/Post/<POST_ID> \
  -H 'Content-Type: application/json'

The response will return the details of the post, including the postedOn attribute, which records when it was created.

4. Exploring Other API Operations

Agentlang provides a full set of CRUD operations for your entities. Here are some additional requests you can try on your own:

List all blog posts


curl http://localhost:8080/blog.core/Post

Update a blog post


curl -X PUT http://localhost:8080/blog.core/Post/<POST_ID> \
  -H 'Content-Type: application/json' \
  -d '{"postedBy": "jj@fractl.io"}'

Delete a blog post


curl -X DELETE http://localhost:8080/blog.core/Post/<POST_ID>

With just a few commands, you can create, read, update, and delete blog posts, all without writing a single line of backend code. Agentlang handles the routing, persistence, and response formatting automatically, so you can focus on defining your entities and business logic.

In the next step of this tutorial, we will add more features to the blog-application, and in that process, explore Agentlang in more depth.