Turgai: an agent harness built on distributed actors

Hi everyone again! :waving_hand::slightly_smiling_face:

I'd like to share Turgai[1]: an agent harness where everything is an actor. Underneath is an object runtime, so Swift code, yours or an agent's, becomes live objects.

Started with agent loops. Reading about them, I kept thinking they look a lot like actors: something owns its state, gets a message, reacts, waits for the next one. That became Hail, a runtime for durable, distributed agents.

Then I went further back, to NeXT. There objects weren't just a way to organize code: they were ready-made parts, and a small team could put a whole web store together from them in weeks. With language models this matters again: a model doesn't need a manual, it can ask an object what it offers and use it. And what it builds can be objects too.

:warning: Early stage. APIs and storage still change, so try it and poke at it, but don't rely on it yet.

What it does

  • Everything is an actor with its own identity and journal. Agents, objects, spaces, conversations. After a crash or restart each one comes back with what it knew, and timers and schedules keep running.
  • Effects are granted, not assumed. As in Hail, file, process and network actions are typed effects. In Turgai a space decides them: its people, groups and bots. If something isn't allowed yet, it asks whoever decides and waits.
  • Any model, through AnyLanguageModel: Apple's on-device model, Ollama, MLX, OpenAI-compatible servers, Anthropic, Gemini.
  • Ways in: HTTP API with one WebSocket per app, a web app, a Mac app with Turgai inside, and Telegram.

Objects: live Swift actors

This is the part I like most. Objects are how Turgai grows while it runs. A new feature, a rule, a tool, a wrapper around your own API: each one is added as an object, and from then on agents in the space can use it. No rebuild, no redeploy, and nothing that already works has to change.

An object is a plain Swift actor, written by you or by an agent. When you ask a bot for something new, it doesn't write a script or a workflow, it writes one of these:

actor Thermometer {
    @Event struct TooHot: Codable {
        var degrees: Double
    }

    func read(degrees: Double) {
        if degrees > 30 { announce(TooHot(degrees: degrees)) }
    }
}

actor Fan {
    @Subscribed var thermometer = Thermometer(id: "kitchen")

    func onTooHot(_ tooHot: Thermometer.TooHot) {
        // Turn on.
    }
}

That actor becomes a live object:

  • Checked like Swift. The code is checked the way swiftc would do it, against everything the object may use: other objects in the space, built-ins, the node's tools. Errors come back in the compiler's words, with the line, so an agent fixes them the way you would.
  • Live and lasting. Stored properties are the state, journaled and kept across restarts. Thermometer(id: "kitchen") is the kitchen thermometer in the space, created the first time it's named. Objects announce events, follow each other, run on schedules and timers. They can also serve a live web page at /websites/<name>/, with button presses arriving as events.
  • Usable by other agents. An object's tools are typed from its own code, so whoever made it, any agent can call it right away. New code starts a new activation, identity and state stay.

Three packages make this work, each usable on its own:

  • Doppel: a doppelgänger of Swift. Checks Swift code the way swiftc would and runs one actor from it live, without compiling. Other actors are handled by the host app. It's for code written at runtime, like code from a model, and for places where swiftc can't run: on a device, in a sandbox, inside an app. Tests keep the checker in agreement with the real compiler on a corpus of real code. It also reports what each type declares, which is where typed tools come from. Started as a fork of Oliver Drobnik's SwiftScript, now rewritten as a checker plus an actor runtime.
  • Discoverable Distributed Actors: actors that explain themselves. Add @Discoverable to a distributed actor, and any caller with its ID can ask what it offers and call it by name with JSON, without importing the Swift type. Schemas come from signatures and doc comments, shaped like a W3C Thing Description. Turgai's built-in objects (Website, Weather) describe themselves to models this way.
  • Cluster Running Actors: work that comes back. A virtual actor keeps its long-lived work through it, a loop or a task. While the work runs, the actor is on a journaled list, and a node starting after a crash brings each actor on the list back by id.

Spaces

A space is a world of its own inside Turgai: its own objects, agents, connections and rules, running beside other spaces on the same server, with nothing reaching from one into another. It's what you extend.

Extending by asking is only safe with permissions, so a space decides what happens in it. Its people are in groups (admins, members, guests), every call and every effect carries who it's on behalf of, and the space decides as it is at that moment. If something isn't allowed yet, like a new object fetching a web page, the space asks whoever may decide, and it waits for the answer.

Built on Swift

All of it is Swift, and the heart of it is swift-distributed-actors: every agent, space, conversation and object is a distributed actor on a cluster, on one machine or many. cluster-virtual-actors gives them identities that outlive any one process, and cluster-event-sourcing their journals. Hail sits on top, for the agents. The web app is HTML written in Swift with Elementary, served by Hummingbird, and turg.ai is generated with Elementary too (@sliemeobn you'll like this!).

Try it

Swift 6.4, macOS 26.4 or Linux.

What's next

Playing with Turgai and improving object runtime. Core is built, but now time to prove it's all working.

Result

What I like is how it fits together. An agent, a space, a conversation and an object are the same kind of thing, an actor with an identity and a journal. A restart brings them all back the same way, and a space decides for all of them the same way. So the code stays small for what it does, about 74k lines of Swift across Turgai, Hail and the three packages, and something new is usually just one more actor.


All models go through AnyLanguageModel, behind the same Foundation Models API. Without it this would be much harder to build. Special thanks to @mattt for reviewing my PRs so quickly and shipping releases so fast.


  1. Turgay means skylark in Turkic languages. ↩︎

7 Likes

Small follow-up :slightly_smiling_face:

I want to extend the ways an LLM writes objects in the future, but one thing surprised me. With Swift, even small models could write them: Apple's FM (think around 3B?), managed it. Mostly simple ones, but still.

I tried python, TS and Lisp, and they all failed. Probably it's the object nature, where Swift just fits better. Still interesting.

1 Like

Elementary mentioned, let's goooo (੭˃ᴗ˂)੭

Looks like quite the project, congrats on shipping!

3 Likes

A (very) small demo in several screenshots:

Very simple prompt, Can you check the ``https://open-meteo.com`` API and create an object that wraps it and can be used to check the weather forecast?, and the agent starts doing a bit of research and writing Swift code at runtime. There's no Swift compiler involved: everything runs through Doppel, so this could work even on a phone with local models:

Result is an object that anyone or agent can use straight away without any restarts or whatever:

Note that each object is durable and long lived, so one create different schedulers and etc., and they can survive restarts and crashes.

You can also check code inside object created by agent:

And this is not just one object in isolation, I can use anything in my environment, e.g. create an object that uses other objects. Like here—newly created wardrobe uses just recently created weather object to check, then asks agent (which basically another object in the system) with response to suggest clothing—all in code and written at runtime.


So long story short it's really Turgai grows while it runs. Need to do a proper video demo.