AgentScript

A domain-specific language for chaining AI and APIs in simple, readable pipelines.

One line replaces hundreds of lines of code.

(pipe (search "AI trends") summarize (email "you@gmail.com"))

What It Does

AgentScript lets you chain AI models with 100+ commands using two s-expression forms: (pipe ...) runs stages in sequence, (par ...) runs them at once. Research topics, generate images and videos, send emails, check stocks, monitor Reddit, read RSS feeds, get weather forecasts, search jobs, run MCP tools, query knowledge graphs — all in one script.

# Morning briefing in one command
(pipe
  (par
    (weather "San Francisco")
    (crypto "BTC,ETH,SOL")
    (stock "AAPL,NVDA,MSFT")
    (news_headlines "technology")
    (rss "hn")
    (reddit "r/golang")
    (job_search "golang contract" "remote"))
  merge
  (ask "morning briefing with weather, markets, headlines, and jobs")
  (notify "slack")
  (email "you@gmail.com"))

Quick Start

git clone https://github.com/vinodhalaharvi/agentscript
cd agentscript
go mod tidy
go build -o agentscript ./cmd/agentscript

export GEMINI_API_KEY="your-key"

# Try it
./agentscript -e '(ask "hello world")'
./agentscript -e '(pipe (search "golang trends") summarize)'
./agentscript -e '(crypto "BTC,ETH,SOL")'
./agentscript -e '(weather "New York")'

The Grammar

AgentScript is written as s-expressions.

program = form+
form    = block | expr
block   = "(" ("block" | "script") option* expr ")"
option  = ":backend" ("memory" | "temporal" | "sibyl")
        | ":mode"    ("static" | "dynamic")
expr    = pipe | par | call | symbol
pipe    = "(" "pipe" expr+ ")"
par     = "(" "par" expr expr+ ")"
call    = "(" symbol literal* ")"
symbol  = bare identifier — a call with no arguments

Two forms define the entire language:

Form	Meaning
`(pipe a b c)`	Kleisli composition — each stage's output feeds the next
`(par a b c)`	Fan-out — branches run concurrently on the same input

The (block ...) wrapper is optional; without it a program runs on the memory backend in static mode. Backend selection lives in the source, never in a runtime flag, so a program always runs the same way wherever it is invoked from. Comments start with ; or //.

Commands

AgentScript ships 100+ commands. The most common are grouped below; the authoritative list is the registry, reachable via script.Grammar().

Core

Command	Example	Description
`search`	`(search "topic")`	Web search via Gemini
`summarize`	`summarize`	Summarize piped input
`ask`	`(ask "question")`	Ask with context
`analyze`	`(analyze "focus")`	Deep analysis
`save`	`(save "file.md")`	Save to local file
`read`	`(read "file.txt")`	Read local file
`list`	`(list ".")`	List directory
`merge`	`merge`	Merge fan-out results

Data

Command	Example	API	Key?
`weather`	`(weather "NYC")`	Open-Meteo	No
`crypto`	`(crypto "BTC,ETH")`	CoinGecko	No
`reddit`	`(reddit "r/golang")`	Reddit JSON	No
`rss`	`(rss "hn")`	Direct HTTP	No
`news`	`(news "AI")`	GNews	Yes
`news_headlines`	`(news_headlines "tech")`	GNews	Yes
`stock`	`(stock "AAPL,NVDA")`	Finnhub	Yes
`job_search`	`(job_search "golang")`	SerpAPI	Yes
`twitter`	`(twitter "golang")`	Twitter API	Yes

Google Workspace

Command	Example	API
`email`	`(email "to@gmail.com")`	Gmail
`calendar`	`(calendar "Meeting 2pm")`	Calendar
`meet`	`(meet "Sprint Review")`	Calendar+Meet
`drive_save`	`(drive_save "path/file")`	Drive
`doc_create`	`(doc_create "Title")`	Docs
`sheet_create`	`(sheet_create "Title")`	Sheets
`sheet_append`	`(sheet_append "id/sheet")`	Sheets
`task`	`(task "todo")`	Tasks
`contact_find`	`(contact_find "John")`	People
`youtube_search`	`(youtube_search "query")`	YouTube

Multimodal (Gemini)

Command	Example	Model
`image_generate`	`(image_generate "robot")`	Imagen 4
`image_analyze`	`(image_analyze "describe")`	Gemini
`video_generate`	`(video_generate "sunset")`	Veo 3.1
`video_analyze`	`(video_analyze "summarize")`	Gemini
`images_to_video`	`images_to_video`	ffmpeg
`text_to_speech`	`(text_to_speech "en")`	Gemini TTS
`translate`	`(translate "Japanese")`	Gemini

Notifications

Command	Example	Service
`email`	`(email "you@gmail.com")`	Gmail
`notify`	`(notify "slack")`	Slack/Discord/Telegram
`whatsapp`	`(whatsapp "+1234567890")`	Twilio

Control Flow

Command	Example	Description
`par`	`(par a b c)`	Run branches concurrently
`when`	`(when "rain > 50")`	Conditional execution (resolves to the `if` builtin)
`foreach`	`(foreach "line")`	Iterate over items
`match`	`match`	Pattern-match on piped input
`fmap` / `pfmap`	`(fmap "cmd")`	Map a command over items (parallel variant: `pfmap`)

MCP (Model Context Protocol)

Command	Example	Description
`mcp_connect`	`(mcp_connect "name" "cmd")`	Connect to an MCP server
`mcp`	`(mcp "server:tool" "args")`	Call an MCP tool
`mcp_list`	`mcp_list`	List connected servers and tools
`mcp_search`	`(mcp_search "query")`	Search the MCP registry
`mcp_agent`	`(mcp_agent "task")`	AI-driven MCP tool selection

Knowledge & Retrieval

Command	Example	Description
`rag_connect` / `rag_index` / `rag_query`	`rag_query "question"`	Postgres + LLM RAG pipeline
`kg_extract` / `kg_query` / `kg_cypher`	`kg_query "question"`	Knowledge graph + GraphRAG
`perplexity`	`(perplexity "query")`	Perplexity-backed search (`_pro`, `_recent`, `_domain` variants)

AI Backends & Tooling

Command	Example	Description
`claude`	`(claude "prompt")`	Claude (Anthropic) completion
`ollama`	`(ollama "prompt")`	Local Ollama model
`agent`	`(agent "task")`	Natural-language → DSL agent
`codereview`	`codereview`	Multi-model code-review debate
`hf_*`	`hf_generate "prompt"`	Hugging Face inference (generate, classify, NER, QA, embeddings, image, speech, ...)

Infrastructure

Command	Example	Description
`exec`	`(exec "go build")`	Run a shell command in a pipeline
`ssl_check` / `ping` / `dns_lookup` / `http_check` / `whois`	`ssl_check "example.com"`	Network diagnostics (pure Go)
`deploy` / `schedule` / `undeploy`	`deploy`	Cloud Run job deploy + Cloud Scheduler
`pdf_fields` / `pdf_fill`	`(pdf_fill "form.pdf")`	AI-powered PDF form filling
`github_pages_html`	`(github_pages_html "Title")`	Deploy HTML to GitHub Pages

Example Pipelines

Daily Job Hunt

(pipe
  (par
    (job_search "golang contract" "remote")
    (job_search "go microservices" "remote"))
  merge
  (ask "deduplicate, format as table, sort by rate")
  (email "you@gmail.com"))

Stock Alert

(pipe (stock "NVDA") (when "change > 5") (notify "slack"))

Tech Digest

(pipe
  (par
    (rss "hn")
    (rss "lobsters")
    (reddit "r/golang" "top")
    (news_headlines "technology"))
  merge
  summarize
  (email "you@gmail.com"))

Multimodal Pipeline

(pipe
  (search "butterflies migration")
  summarize
  (text_to_speech "en")
  (image_generate "monarch butterflies migrating")
  images_to_video
  (youtube_upload "Butterfly Migration"))

Nested Fan-out

(pipe
  (par
    (pipe
      (par
        (pipe (search "React pros cons") analyze)
        (pipe (search "Vue pros cons") analyze)
        (pipe (search "Angular pros cons") analyze))
      merge
      (ask "summarize frontend frameworks"))
    (pipe
      (par
        (pipe (search "Node.js backend") analyze)
        (pipe (search "Go backend") analyze))
      merge
      (ask "summarize backend options")))
  merge
  (ask "full-stack recommendation")
  (save "recommendation.md"))

Natural Language Mode

Prose-to-program translation lives in pkg/script (Translate, BuildPrompt) and its prompt teaches the s-expression syntax, but it is not currently wired to a CLI flag — the old -n mode went with the legacy binary.

RSS Feed Shortcuts

No URL needed — just use the shortcut name:

Shortcut	Feed
`hn`	Hacker News
`golang`	Go Blog
`lobsters`	Lobste.rs
`techcrunch`	TechCrunch
`kubernetes`	Kubernetes Blog
`anthropic`	Anthropic Blog
`github-blog`	GitHub Blog
`reddit-golang`	r/golang RSS
`dev-to`	Dev.to

30+ shortcuts available. Run rss with no args to see all.

Architecture

Natural Language ─── Gemini/Claude translates ──→ AgentScript source
                                                      │
                                                 s-expression reader
                                                 (pkg/script/sexpr)
                                                      │
                                                     AST
                                                      │
                                                Runtime executor
                                                ┌─────┴─────┐
                                           Sequential    Fan-out
                                            (pipe)        (par)
                                                │            │
                                          Plugin registry  goroutines
                                                │
                          ┌──────────┬──────────┼──────────┬──────────┐
                       Gemini      MCP         data       cloud      AI
                        APIs      servers     plugins    plugins   backends

Each integration is a plugin that registers its DSL commands with the runtime. Plugins live under plugins/<vendor>/; shared API clients and the plugin interface live under pkg/.

DSL → Sibyl translator (in progress)

A second execution path is being built: an arrow-first translator that compiles AgentScript into Sibyl DAGs for durable, Temporal-backed execution. The design is documented in docs/dsl-to-sibyl-translator.md; the translator code is under pkg/script/. The existing in-process runtime continues to serve as the fast "memory" backend.

Project Structure

agentscript/
├── cmd/
│   └── agentscript/       # CLI entry point (-e, file, stdin, --dry-run)
├── internal/agentscript/  # Runtime, grammar, registry, translator
│   ├── grammar.go         # interpreter Program/Statement/Command types
│   ├── runtime.go         # Command execution engine
│   ├── registry.go        # Plugin registration
├── pkg/                   # Shared clients + plugin interface
│   ├── plugin/            # The plugin.Plugin contract
│   ├── claude/            # Claude API client
│   ├── gemini/            # Gemini API client
│   ├── google/            # Google Workspace helpers
│   └── openai/            # OpenAI API client
├── plugins/               # One directory per integration
│   ├── weather/ crypto/ stock/ news/ reddit/ rss/ twitter/ jobsearch/
│   ├── mcp/ mcpagent/ mcpsearch/ rag/ kg/ perplexity/ huggingface/
│   ├── github/ cloudrun/ network/ pdffill/ datatable/ ollama/
│   ├── agent/ review/ plugagent/ notify/ whatsapp/ exec/
│   └── cache/             # Shared file-based result cache
├── docs/
│   └── dsl-to-sibyl-translator.md
├── examples/              # *.as scripts
└── Makefile

Environment Variables

# Required
export GEMINI_API_KEY="..."

# Data APIs (all have free tiers)
export SERPAPI_KEY="..."           # Jobs, news/stock fallback (100/mo free)
export FINNHUB_API_KEY="..."      # Stocks (60/min free)
export GNEWS_API_KEY="..."        # News (100/day free)
export TWITTER_BEARER_TOKEN="..." # Twitter search

# Google Workspace (OAuth)
export GOOGLE_CREDENTIALS_FILE="credentials.json"

# Notifications
export SLACK_WEBHOOK_URL="..."
export DISCORD_WEBHOOK_URL="..."
export TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."

# WhatsApp (Twilio)
export TWILIO_ACCOUNT_SID="..."
export TWILIO_AUTH_TOKEN="..."
export TWILIO_WHATSAPP_FROM="whatsapp:+14155238886"

# 4 commands need ZERO keys: weather, crypto, reddit, rss

Running

# Expression mode
./agentscript -e '(pipe (search "topic") summarize)'

# File mode — the file is a positional argument, there is no -f
./agentscript examples/tech-digest.as

# Stdin
cat examples/research.as | ./agentscript

# Compile a temporal program and print its Plan, no cluster needed
./agentscript --dry-run examples/durable-echo.as

# Verbose mode (debug)
./agentscript -v -e '(crypto "BTC")'

Testing

# Run the whole suite
go test ./...

# Race detector (matches CI)
go test -race ./...

# A single package
go test ./pkg/script/...

CI (GitHub Actions) runs go mod tidy, go vet -structtag=false, gofmt, staticcheck, go test -race, and go build on every push and PR. See .github/workflows/ci.yml.

Built With

Go 1.23 — Runtime engine
Gemini API — Text, Imagen 4, Veo 3.1, TTS
Claude API — Completions, code review, agents
Model Context Protocol — Tool servers
Google Workspace APIs — Gmail, Calendar, Drive, Docs, Sheets, Forms, YouTube, Tasks
Open-Meteo — Weather (free)
CoinGecko — Crypto prices (free)
SerpAPI — Job search, news, finance
Finnhub — Stock quotes
GNews — News articles
Twilio — WhatsApp messaging

Links

Demo: https://youtube.com/watch?v=6yJa5LiUS9U
DevPost: https://devpost.com/software/agent-script
Author: Vinod Halaharvi

License

MIT

Navigation Menu

Repository files navigation

AgentScript

What It Does

Quick Start

The Grammar

Commands

Core

Data

Google Workspace

Multimodal (Gemini)

Notifications

Control Flow

MCP (Model Context Protocol)

Knowledge & Retrieval

AI Backends & Tooling

Infrastructure

Example Pipelines

Daily Job Hunt

Stock Alert

Tech Digest

Multimodal Pipeline

Nested Fan-out

Natural Language Mode

RSS Feed Shortcuts

Architecture

DSL → Sibyl translator (in progress)

Project Structure

Environment Variables

Running

Testing

Built With

Links

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd/agentscript		cmd/agentscript
docs		docs
examples		examples
internal/agentscript		internal/agentscript
pkg		pkg
plugins		plugins
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation

AgentScript

What It Does

Quick Start

The Grammar

Commands

Core

Data

Google Workspace

Multimodal (Gemini)

Notifications

Control Flow

MCP (Model Context Protocol)

Knowledge & Retrieval

AI Backends & Tooling

Infrastructure

Example Pipelines

Daily Job Hunt

Stock Alert

Tech Digest

Multimodal Pipeline

Nested Fan-out

Natural Language Mode

RSS Feed Shortcuts

Architecture

DSL → Sibyl translator (in progress)

Project Structure

Environment Variables

Running

Testing

Built With

Links

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages