# `Agentic`

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}`

# `new_workspace`

Scaffold a new workspace directory with default identity files.

# `resume`

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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*