Agentic (agentic v0.2.2)

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.

Quick Start

Agentic.run(
  prompt: "Help me refactor this module",
  workspace: "/path/to/workspace",
  callbacks: %{
    llm_chat: fn params -> MyLLM.chat(params) end
  }
)

Callbacks

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 Agentic.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}

Summary

Functions

new_workspace(path, opts \\ [])

Scaffold a new workspace directory with default identity files.

resume(opts)

Resume a previous session from its transcript.

run(opts)

Run the agent loop.

Functions

new_workspace(path, opts \\ [])

Scaffold a new workspace directory with default identity files.

resume(opts)

Resume a previous session from its transcript.

Loads the transcript for the given session, reconstructs the conversation messages, and starts the pipeline from where it left off.

Options

:session_id — session to resume (required)
:workspace — workspace directory path (required)
:callbacks — map of callback functions (required, at minimum :llm_chat)
:transcript_backend — module implementing Agentic.Persistence.Transcript (optional, defaults to Transcript.Local)
All other options from run/1 are supported and override transcript values.

run(opts)

Run the agent loop.

Options

:prompt — user prompt (required)
:workspace — workspace directory path (required)
:callbacks — map of callback functions (required, at minimum :llm_chat)
:system_prompt — custom system prompt (optional, auto-assembled if omitted)
:history — list of prior conversation messages (optional)
:profile — loop profile (optional, default :agentic)
:mode — execution mode :agentic | :agentic_planned | :turn_by_turn | :conversational (optional, overrides :profile)
:plan — pre-built plan map for :agentic_planned mode, skips planning phase (optional)
:model_tier — model tier for LLM calls (optional, default :primary)
:model_selection_mode — :manual or :auto (optional, default :manual)
:model_preference — :optimize_price or :optimize_speed (optional, default :optimize_price, only used in :auto mode)
:model_filter — constrain model candidates: :free_only or nil (optional, only used in :auto mode)
:session_id — for telemetry and event tracking (optional)
:user_id — for API key resolution (optional)
:caller — pid to receive events (optional, defaults to self())
:workspace_id — workspace identifier for ContextKeeper (optional)
:cost_limit — per-session cost limit in USD (optional, default 5.0)
:model_routes — fallback model routes for routing (optional, e.g. [primary: [...]])
:strategy — orchestration strategy id or module (optional, default :default)
:strategy_opts — extra opts passed to strategy init/1 (optional)

Returns {:ok, %{text: string, cost: float, tokens: integer, steps: integer}} or {:error, reason}.