secai

AI-gent Workflows

AI-gent Workflows (aka secai) is a platform for AI Agents with a local reasoning layer. It's implemented on top of a unified state graph and makes a solid foundation for complex, proactive, and long-lived AI Agents with deep and structured memory. It offers a dedicated set of devtools and is written in the Go programming language. By having a graph-based flow, secai allows for precise behavior modeling of agents, including interruptions and fault tolerance.

• Demos
  • User Demo
  • Platform Demo
• Features
  • Implementation
  • Comparison
• Try It
  • Examples
• Screenshots
  • User
  • Platform
  • Dashboards
• Documentation
• Getting Started
• User Interfaces
  • Chat
  • Stories
  • Clock
• Bash Scripts

User Demo

Screenshots and YouTube are also available.

[!NOTE] User demo (7m captions-only) showcasing a cooking assistant which helps to pick a recipe from ingredients AND cook it.

Platform Demo

Screenshots and YouTube are also available.

[!NOTE] Platform demo (5m captions-only), showcasing all nine ways an agent can be seen, in addition to the classic chat view.

Features

• multi-prompt agency
  • each state can have a prompt bound to it, with dedicated history and documents
• atomic consensus with relations and negotiation
  • eg states excluding each other can't be active simultaneously
• dedicated DSL layer for bot schema
  • suitable for non-coding authors
• structured prompt input/output via JSON schemas
• declarative flow definitions for non-linear flows
• cancellation support (interrupts)
• offer list / menu
• prompt history
  • in SQL (embedded SQLite)
  • in JSONL (stdout)
• proactive stories with actors
• LLM triggers (orienting)
  • on prompts and timeouts
• dynamic flow graph for the memory
  • LLM creates an actionable state-machine
• UI components
  • chat
  • stories
  • clock
• platforms
  • SSH (all platforms)
  • Desktop PWA (all platforms)
  • Mobile PWA (WIP)

Goals

• precision
• traceability
• privacy

Goals

• precision
• traceability
• privacy

Devtools

The following devtools are for the agent, the agent's dynamic memory, and tools (all of which are the same type of state machine).

• REPL & CLI
• TUI debugger (+dashboards)
• automatic diagrams (D2 SVGs)
• automatic observability (Prometheus, Grafana, Jaeger)

Tools

• websearch (searxng)
• HTML scrape (colly)
• browser scrape (chromedp) (WIP)

Implementation

• pure Golang
• typesafe state-machine and prompt schemas
• asyncmachine-go for graphs and control flow
• instructor-go for the LLM layer
  • OpenAI (DeepSeek, LMStudio), Gemini, Anthropic, Cohere
• invopop/jsonschema for JSON schemas
• network transparency (aRPC, debugger, REPL)
• structured concurrency (multigraph-based)
• cview, and asciigraph for UIs

Components

• Agent (actor)
  • state-machine schema
  • prompts
  • tools
• Tool (actor)
  • state-machine schema
• Memory
  • state-machine schema
• Prompt (state)
  • params schema
  • result schema
  • history log
  • documents
• Stories (state)
  • actors
  • state machines
• Document
  • title
  • content

Comparison

Go vs Python

• just works, batteries included, no magic
• 1 package manager vs 4
• single binary vs interpreted multi-file source
• coherent static typing vs maybe
• easy & stable vs easy
• no ecosystem fragmentation
• million times faster /s
• relevant xkcd

Try It

Unlike Python apps, you can start it with a single command:

• Download a binary release (Linux, MacOS, Windows)
• Set an API key in config.kdl
• Run ./aigent-cook and copy-paste-run the SSH line into another terminal
• You'll see files being created in ./tmp

AI-gent Cook v0.4.0

TUI:
$ ssh localhost -p 7955 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no

Log:
$ tail -f tmp/cook/cook.jsonl -n 100 | fblog -d -x msg -x time -x level

REPL:
$ ./arpc --dir tmp/cook

https://ai-gents.work

Examples

Code snippets from /examples/research (ported from AtomicAgents). Both the state and prompt schemas are pure and debuggable Golang code.

State Schema

// ResearchStatesDef contains all the states of the Research state machine.
type ResearchStatesDef struct {
    *am.StatesBase

    CheckingInfo string
    NeedMoreInfo string

    SearchingLLM string
    SearchingWeb string
    Scraping     string

    Answering string
    Answered  string

    *ss.AgentStatesDef
}

// ResearchGroupsDef contains all the state groups Research state machine.
type ResearchGroupsDef struct {
    Info    S
    Search  S
    Answers S
}

// ResearchSchema represents all relations and properties of ResearchStates.
var ResearchSchema = SchemaMerge(
    // inherit from Agent
    ss.AgentSchema,

    am.Schema{

        // Choice "agent"
        ssR.CheckingInfo: {
            Require: S{ssR.Start, ssR.Prompt},
            Remove:  sgR.Info,
        },
        ssR.NeedMoreInfo: {
            Require: S{ssR.Start},
            Add:     S{ssR.SearchingLLM},
            Remove:  sgR.Info,
        },

        // Query "agent"
        ssR.SearchingLLM: {
            Require: S{ssR.NeedMoreInfo, ssR.Prompt},
            Remove:  sgR.Search,
        },
        ssR.SearchingWeb: {
            Require: S{ssR.NeedMoreInfo, ssR.Prompt},
            Remove:  sgR.Search,
        },
        ssR.Scraping: {
            Require: S{ssR.NeedMoreInfo, ssR.Prompt},
            Remove:  sgR.Search,
        },

        // Q&A "agent"
        ssR.Answering: {
            Require: S{ssR.Start, ssR.Prompt},
            Remove:  SAdd(sgR.Info, sgR.Answers),
        },
        ssR.Answered: {
            Require: S{ssR.Start},
            Remove:  SAdd(sgR.Info, sgR.Answers, S{ssR.Prompt}),
        },
    })

var sgR = am.NewStateGroups(ResearchGroupsDef{
    Info:    S{ssR.CheckingInfo, ssR.NeedMoreInfo},
    Search:  S{ssR.SearchingLLM, ssR.SearchingWeb, ssR.Scraping},
    Answers: S{ssR.Answering, ssR.Answered},
})

Prompt Schema

func NewCheckingInfoPrompt(agent secai.AgentApi) *secai.Prompt[ParamsCheckingInfo, ResultCheckingInfo] {
    return secai.NewPrompt[ParamsCheckingInfo, ResultCheckingInfo](
        agent, ssR.CheckingInfo, `
            - You are a decision-making agent that determines whether a new web search is needed to answer the user's question.
            - Your primary role is to analyze whether the existing context contains sufficient, up-to-date information to
            answer the question.
            - You must output a clear TRUE/FALSE decision - TRUE if a new search is needed, FALSE if existing context is
            sufficient.
        `, `
            1. Analyze the user's question to determine whether or not an answer warrants a new search
            2. Review the available web search results 
            3. Determine if existing information is sufficient and relevant
            4. Make a binary decision: TRUE for new search, FALSE for using existing context
        `, `
            Your reasoning must clearly state WHY you need or don't need new information
            If the web search context is empty or irrelevant, always decide TRUE for new search
            If the question is time-sensitive, check the current date to ensure context is recent
            For ambiguous cases, prefer to gather fresh information
            Your decision must match your reasoning - don't contradict yourself
        `)
}

// CheckingInfo (Choice "agent")

type ParamsCheckingInfo struct {
    UserMessage  string
    DecisionType string
}

type ResultCheckingInfo struct {
    Reasoning string `jsonschema:"description=Detailed explanation of the decision-making process"`
    Decision  bool   `jsonschema:"description=The final decision based on the analysis"`
}

Read the schema file in full.

Screenshots

Screenshots User Demo

• Slide Deck

Intro	AI-gent Cook	Debugger 1	Debugger 2	Memory & Stories
User Interfaces	Outro
State Schema

Screenshots Platform Demo

SVG graph	am-dbg	Grafana	Jaeger	REPL
SQL	IDE	Bash	Prompts
State Schema

Screenshots Dashboards

Dashboard 1

Dashboard 2

Documentation

• secai: API / Docs
• asyncmachine-go: API / Docs
• instructor-go: API / Docs
• tview: API / Docs
• cview: API

Getting Started

We can use one of the examples as a starting template. It allows for further semver updates of the base framework.

1. Choose the source example
   • export SECAI_EXAMPLE=cook
   • export SECAI_EXAMPLE=research (broken in v0.4.0)
2. git clone https://github.com/pancsta/secai.git
3. install task ./secai/scripts/deps.sh
4. copy the agent cp -R secai/examples/$SECAI_EXAMPLE MYAGENT
5. cd MYAGENT && go mod init github.com/USER/MYAGENT
6. get fresh configs
   1. task sync-taskfile
   2. task sync-configs
7. start it task start
8. look around task --list-all
9. configure dev stuff cp .env.template .env
10. configure the bot $EDITOR config.kdl

User Interfaces

Several TUIs with dedicated UI states are included in /tui:

Chat TUI

• senders & msgs scrollable view with links
• multiline prompt with blocking and progress
• send / stop button

Stories TUI

• list of stories with activity status (non-actionable)
• dynamic buttons and progress bars (actionable)

Clockmoji TUI

• recent clock changes plotted by asciigraph

Bash Scripts

arpc offers CLI access to remote agents, including subscription. It's perfect for quick and simple integrations, scripts, or experiments.

Example: arpc -f tmp/research.addr -- when . Requesting && echo "REQUESTING"

1. Connect to the address from tmp/research.addr
2. When the last connected agent (.) goes into state Requesting
3. Print "REQUESTING" and exit

License

To help keep AI open, this project migrated to GPL starting from v0.3.0.

Acknowledgements

• AtomicAgents
• SecretAgent Soma.fm