Agentic

A composable AI agent runtime for Elixir. Provides a complete agent loop with skills, working memory, knowledge persistence, and tool use. Drop it into any Elixir project to get a fully functional AI agent.

Features

• Composable Pipeline — Middleware-style stage pipeline lets you mix and match agent behaviors
• Multiple Profiles — Four built-in profiles: agentic, agentic_planned, turn_by_turn, conversational
• Tool Execution — Built-in file operations, glob, grep, and extensibility for custom tools
• Skills System — YAML-defined skills that extend agent capabilities at runtime
• Working Memory — Context keeper with fact extraction and commitment detection
• Persistence — Transcript, plan, and knowledge persistence with pluggable backends
• Cost Controls — Per-session cost limits and token usage tracking
• Telemetry — Full event instrumentation via Telemetry

Installation

Add Agentic to your dependencies in mix.exs:

def deps do
  [
    {:agentic, "~> 0.1.0"}
  ]
end

Database Backend

Agentic uses Recollect for knowledge persistence. Recollect supports two database backends:

Option A: libSQL (Recommended for new projects) Single-file SQLite with native vector support. Zero configuration.

def deps do
  [
    {:agentic, "~> 0.1.0"},
    {:ecto_libsql, "~> 0.9"}
  ]
end

Configure Recollect:

config :recollect,
  database_adapter: Recollect.DatabaseAdapter.LibSQL,
  repo: MyApp.Repo,
  embedding: [
    provider: Recollect.Embedding.OpenRouter,
    dimensions: 768
  ]

Option B: PostgreSQL (For existing installations) Traditional server-based database with pgvector extension.

def deps do
  [
    {:agentic, "~> 0.1.0"},
    {:postgrex, "~> 0.19"},
    {:pgvector, "~> 0.3"}
  ]
end

Configure Recollect:

config :recollect,
  database_adapter: Recollect.DatabaseAdapter.Postgres,
  repo: MyApp.Repo,
  embedding: [
    provider: Recollect.Embedding.OpenRouter,
    dimensions: 1536
  ]

Quick Start

result = Agentic.run(
  prompt: "Create a README.md file for my project",
  workspace: "/path/to/your/project",
  callbacks: %{
    llm_chat: fn params -> MyLLM.chat(params) end
  }
)

{:ok, %{text: response, cost: 0.05, tokens: 150, steps: 3}}

Architecture

Agentic uses a stage pipeline architecture. Each stage wraps the next, receiving the context and a next function to call downstream:

ContextGuard → ProgressInjector → LLMCall → ModeRouter → ToolExecutor → CommitmentGate

• Engine builds the pipeline from stage modules
• Profile maps named profiles to stage lists and configuration
• Phase is a pure-function state machine with validated transitions
• Context is the loop state passed through every stage

Profiles

Callbacks API

The callbacks map connects Agentic to your LLM provider and external systems:

Required

• :llm_chat — (params) -> {:ok, response} | {:error, term}

Optional

• :execute_tool — custom tool handler (defaults to built-in tools)
• :on_event — (event, ctx) -> :ok for UI streaming
• :on_response_facts — (ctx, text) -> :ok for custom fact processing
• :on_tool_facts — (ws_id, name, result, turn) -> :ok
• :on_persist_turn — (ctx, text) -> :ok
• :get_tool_schema — (name) -> {:ok, schema} | {:error, reason}
• :get_secret — (service, key) -> {:ok, value} | {:error, reason}
• :knowledge_search — (query, opts) -> {:ok, entries} | {:error, term}
• :knowledge_create — (params) -> {:ok, entry} | {:error, term}
• :knowledge_recent — (scope_id) -> {:ok, entries} | {:error, term}
• :search_tools — (query, opts) -> [result]
• :execute_external_tool — (name, args, ctx) -> {:ok, result} | {:error, reason}

Core Tools

Agentic ships with built-in tools for file operations:

• file_read — Read file contents
• file_write — Write or overwrite files
• file_edit — Apply targeted edits using line ranges
• glob — Find files by pattern
• grep — Search file contents
• bash — Execute shell commands
• task — Delegate to sub-agents
• memory — Store and retrieve facts
• skills_list — List available skills
• skills_apply — Apply a skill to the workspace
• gateway — Query external services

Extend via the skills system or custom callbacks.

Storage Backends

• Transcript — Session history with event streaming
• Plan — Structured task plans (for :agentic_planned mode)
• Knowledge — Persistent fact storage with search
• Context — Workspace context with pluggable backends

All backends have a :local file-based implementation.

Configuration

Agentic.run(
  prompt: "...",
  workspace: "/path",
  callbacks: %{llm_chat: &my_llm/1},
  profile: :agentic,          # which profile to use
  mode: :agentic,            # shorthand for profile
  system_prompt: "...",      # custom system prompt
  history: [...],            # prior messages
  model_tier: :primary,      # which model tier to use
  cost_limit: 5.0,          # per-session cost limit in USD
  session_id: "agx-...",     # custom session ID
  user_id: "user-123",       # for API key resolution
  plan: %{...}               # pre-built plan (for agentic_planned)
)

Development

mix deps.get          # Install dependencies
mix setup             # Setup database
mix test             # Run tests
mix format           # Format code
mix dialyzer         # Type check

License

BSD-3-Clause — See LICENSE for details.

Contributing

Contributions welcome. Please ensure tests pass and dialyzer is clean before submitting PRs.