agentik-framework

Agentik (A CLI‑First Modular Agent Framework)

Agentik is a developer‑friendly framework for building LLM agents that run via OpenRouter. It emphasizes: clean YAML configs, a batteries‑included CLI, pluggable tools with safety policies, rich JSONL transcripts, and a dev watcher for rapid inner‑loop iteration.

---

Table of Contents

1. Prerequisites

2. Installation

3. Configure OpenRouter

4. Verify Setup

5. Quick Start

6. Configuration Primer

7. CLI Reference (with Windows PowerShell and macOS/Linux examples)

   • version, self-test, init
   • new (agent|tool)
   • template (list|apply|pull)
   • run
   • dev watch
   • keys (set|show)
   • models list
   • tools (list|info|run)
   • validate file
   • batch run
   • memory (init|recall|summarize|clear|path)
   • eval run
   • config path

8. Built‑in Tools & Policies

9. Transcripts & Cost Estimation

10. Quick Reference Table

11. Troubleshooting

12. Development

---

Prerequisites

• Python 3.10+

---

Installation

Windows (PowerShell)

pip install agentik-framework

macOS/Linux

pip install agentik-framework

---

Configure OpenRouter

Agentik uses OpenRouter for LLM calls. Provide your key via env var or store it in Agentik’s RC.

Windows (PowerShell)

setx OPENROUTER_API_KEY "sk-or-XXXXXXXXXXXXXXXX"
# Close & reopen PowerShell so the env var is available in new sessions

macOS/Linux (bash/zsh)

echo 'export OPENROUTER_API_KEY="sk-or-XXXXXXXXXXXXXXXX"' >> ~/.bashrc
source ~/.bashrc   # or: source ~/.zshrc

Store via Agentik RC (either scope):

agentik keys set openrouter sk-or-XXXXXXXXXXXXXXXX --global
# or
agentik keys set openrouter sk-or-XXXXXXXXXXXXXXXX --local

---

Verify Setup

Windows (PowerShell)

agentik self-test
agentik models list --filter gpt --refresh   # optional

macOS/Linux

agentik self-test
agentik models list --filter gpt --refresh

---

Quick Start

1. Initialize a project

PowerShell

mkdir my-agent; cd my-agent
agentik init . --template basic --name "My Agent Project"

macOS/Linux

mkdir my-agent && cd my-agent
agentik init . --template basic --name "My Agent Project"

2. Scaffold an agent

PowerShell

agentik new agent research `
  --template basic `
  --tools http_fetch,html_to_text,write_file `
  --with-tests `
  --to .

macOS/Linux

agentik new agent research \
  --template basic \
  --tools http_fetch,html_to_text,write_file \
  --with-tests \
  --to .

3. Minimal config (save as agents/agent.yaml)

agent:
  name: ResearchBot
  goal: "Research and summarize information."
  loop:
    max_steps: 3
    reflect: true

llm:
  model: openai/gpt-4o-mini
  temperature: 0.3

memory:
  type: json
  path: ./memory/research.json

policies:
  allow_network: true
  allow_filesystem: true

tools:
  - http_fetch
  - html_to_text
  - write_file

4. Run your agent

PowerShell

agentik run .\agents\agent.yaml `
  -p "Summarize the main differences between GPT-4o and small LLMs in 5 bullets." `
  --profile fast `
  --stream `
  --save-transcript .\runs\first-run.jsonl

macOS/Linux

agentik run ./agents/agent.yaml \
  -p "Summarize the main differences between GPT-4o and small LLMs in 5 bullets." \
  --profile fast \
  --stream \
  --save-transcript ./runs/first-run.jsonl

5. Use the dev watcher (auto re‑run on save)

PowerShell tip: quote your globs (e.g., '**/*.py') so the shell doesn’t expand them.

PowerShell

agentik dev watch .\agents\agent.yaml `
  --prompt "Summarize this project in 3 bullets." `
  --path . `
  --include '**/*.py' --include '**/*.yaml' --include 'templates/**' `
  --exclude '.venv/**' --exclude 'runs/**' `
  --save-transcripts .\runs `
  --profile dev `
  --stream

macOS/Linux

agentik dev watch ./agents/agent.yaml \
  --prompt "Summarize this project in 3 bullets." \
  --path . \
  --include '**/*.py' --include '**/*.yaml' --include 'templates/**' \
  --exclude '.venv/**' --exclude 'runs/**' \
  --save-transcripts ./runs \
  --profile dev \
  --stream

---

Configuration Primer

• YAML config defines the agent (goal, loop), LLM (model, temperature), memory store, policies, and tools.

• Profiles (CLI --profile) apply overrides:

  • fast: {max_steps=2, reflect=false, temperature=0.2}
  • thorough: {max_steps=6, reflect=true, temperature=0.3}
  • deterministic: {temperature=0.0, reflect=false}
  • creative: {temperature=0.9, reflect=false}
  • cheap: {temperature=0.2} (keeps configured model)
  • dev: {max_steps=3, reflect=false, temperature=0.3}

• Precedence: YAML → RC/env → CLI overrides → profile overrides.

---

CLI Reference

Below, every command shows a signature and examples for Windows PowerShell and macOS/Linux.

Version & Environment

agentik version

Print CLI version.

PowerShell

agentik version

macOS/Linux

agentik version

agentik self-test

Show Python/OS info, OpenRouter key presence, and RC location.

PowerShell

agentik self-test

macOS/Linux

agentik self-test

---

Project Scaffolding

agentik init

agentik init [PATH] --template TEXT --force --name TEXT

• PATH default .
• --template default basic
• --force overwrite existing files
• --name project name override

PowerShell

agentik init . --template basic --name "Demo"

macOS/Linux

agentik init . --template basic --name "Demo"

agentik new agent

agentik new agent NAME \
  --template TEXT \
  --tools "t1,t2" \
  --memory [dict|json] \
  --memory-path PATH \
  --to DIR \
  --with-tests \
  --force

PowerShell

agentik new agent helper `
  --template basic `
  --tools http_fetch,html_to_text `
  --memory json `
  --memory-path .\memory\agent.json `
  --to . `
  --with-tests `
  --force

macOS/Linux

agentik new agent helper \
  --template basic \
  --tools http_fetch,html_to_text \
  --memory json \
  --memory-path ./memory/agent.json \
  --to . \
  --with-tests \
  --force

agentik new tool

agentik new tool NAME --template [python] --to DIR --with-tests --force

PowerShell

agentik new tool web_fetcher --template python --to . --with-tests --force

macOS/Linux

agentik new tool web_fetcher --template python --to . --with-tests --force

---

Templates

agentik template list

List built‑ins.

PowerShell

agentik template list

macOS/Linux

agentik template list

agentik template apply

agentik template apply kind/name --to DIR --force --name TEXT

PowerShell

agentik template apply agent/basic --to . --force --name MyBot

macOS/Linux

agentik template apply agent/basic --to . --force --name MyBot

agentik template pull

Pull a git repo or zip into templates/third_party.

PowerShell

agentik template pull https://example.com/my-templates.zip --to .

macOS/Linux

agentik template pull https://example.com/my-templates.zip --to .

---

Running Agents

agentik run

agentik run CONFIG \
  -p/--prompt TEXT \
  --model TEXT \
  --temperature FLOAT \
  --stream \
  --dry-run \
  --save-transcript PATH \
  --profile [fast|thorough|deterministic|creative|cheap|dev|none] \
  --tag TAG  (repeatable) \
  --note TEXT \
  --run-id TEXT \
  --obs-max-chars INT

PowerShell

agentik run .\agents\agent.yaml `
  -p "Five bullet summary of topic X" `
  --profile fast `
  --stream `
  --save-transcript .\runs\out.jsonl

macOS/Linux

agentik run ./agents/agent.yaml \
  -p "Five bullet summary of topic X" \
  --profile fast \
  --stream \
  --save-transcript ./runs/out.jsonl

---

Developer Watch Mode

agentik dev watch

agentik dev watch CONFIG \
  -p/--prompt TEXT \
  --prompt-file PATH \
  --path PATH          # repeatable; default "." \
  --include GLOB       # repeatable; default ["**/*.py", "**/*.yml", "**/*.yaml", "**/*.json", "**/*.md", "templates/**", "tools/**"] \
  --exclude GLOB       # repeatable \
  --interval FLOAT     # default 0.6 \
  --debounce FLOAT     # default 0.5 \
  --clear/--no-clear   # default clear \
  --stream/--no-stream # default stream \
  --profile dev        # default "dev" \
  --save-transcripts DIR \
  --obs-max-chars INT  # default 800 \
  --no-initial-run \
  --tag TAG            # repeatable; default ["dev"] \
  --note TEXT

PowerShell

agentik dev watch .\agents\agent.yaml `
  --prompt "Echo the date" `
  --include '**/*.py' `
  --exclude '.venv/**' `
  --save-transcripts .\runs

macOS/Linux

agentik dev watch ./agents/agent.yaml \
  --prompt "Echo the date" \
  --include '**/*.py' \
  --exclude '.venv/**' \
  --save-transcripts ./runs

---

Keys & Models

agentik keys set openrouter

Store an API key in RC.

PowerShell

agentik keys set openrouter sk-or-... --global
# or
agentik keys set openrouter sk-or-... --local

macOS/Linux

agentik keys set openrouter sk-or-... --global
# or
agentik keys set openrouter sk-or-... --local

agentik keys show

Display masked key (env & RC) and RC scope/path.

PowerShell

agentik keys show

macOS/Linux

agentik keys show

agentik models list

List OpenRouter models (with optional cache bypass).

PowerShell

agentik models list --filter gpt --refresh

macOS/Linux

agentik models list --filter gpt --refresh

---

Tools (Discovery & Direct Runs)

agentik tools list

List discoverable tools.

PowerShell

agentik tools list

macOS/Linux

agentik tools list

agentik tools info NAME

Show class & description.

PowerShell

agentik tools info http_fetch

macOS/Linux

agentik tools info http_fetch

agentik tools run NAME

Call a tool directly (no agent loop). Values auto‑coerce: true/false → bool; 1→int; 1.2→float; else string. Quote values with spaces/HTML.

PowerShell

agentik tools run http_fetch --arg url=https://example.com --arg ttl=3600 --arg allow_network=true --json
agentik tools run html_to_text --arg "html=<p>Hello</p>" --arg keep_newlines=true --json
agentik tools run write_file --arg path=out\hello.txt --arg "content=Hello" --arg allow_filesystem=true --json

macOS/Linux

agentik tools run http_fetch --arg url=https://example.com --arg ttl=3600 --arg allow_network=true --json
agentik tools run html_to_text --arg 'html=<p>Hello</p>' --arg keep_newlines=true --json
agentik tools run write_file --arg path=out/hello.txt --arg 'content=Hello' --arg allow_filesystem=true --json

---

Validation & Batch

agentik validate file

Validate YAML; optionally print effective config after CLI overrides.

PowerShell

agentik validate file .\agents\agent.yaml `
  --show-effective `
  --model openai/gpt-4o-mini `
  --temperature 0.2 `
  --max-steps 2

macOS/Linux

agentik validate file ./agents/agent.yaml \
  --show-effective \
  --model openai/gpt-4o-mini \
  --temperature 0.2 \
  --max-steps 2

agentik batch run

Run prompts from CSV/JSONL and write JSONL results.

PowerShell

agentik batch run .\prompts.jsonl `
  --column prompt `
  --out .\results.jsonl `
  --model openai/gpt-4o-mini `
  --temperature 0.2

macOS/Linux

agentik batch run ./prompts.jsonl \
  --column prompt \
  --out ./results.jsonl \
  --model openai/gpt-4o-mini \
  --temperature 0.2

---

Memory Helpers

agentik memory init

Initialize store and add an initial record.

PowerShell

agentik memory init --type json --path .\memory\agentik.json

macOS/Linux

agentik memory init --type json --path ./memory/agentik.json

agentik memory recall

PowerShell

agentik memory recall --n 10 --config .\agents\agent.yaml

macOS/Linux

agentik memory recall --n 10 --config ./agents/agent.yaml

agentik memory summarize

PowerShell

agentik memory summarize --n 20 --max-chars 1200 --config .\agents\agent.yaml

macOS/Linux

agentik memory summarize --n 20 --max-chars 1200 --config ./agents/agent.yaml

agentik memory clear

PowerShell

agentik memory clear --config .\agents\agent.yaml

macOS/Linux

agentik memory clear --config ./agents/agent.yaml

agentik memory path

PowerShell

agentik memory path --config .\agents\agent.yaml

macOS/Linux

agentik memory path --config ./agents/agent.yaml

---

Lightweight Eval Harness

agentik eval run

Each JSONL line should have prompt, and optional expect_contains[] and/or expect_regex.

PowerShell

agentik eval run .\tests.jsonl --config .\agents\agent.yaml --out .\eval_results.jsonl

macOS/Linux

agentik eval run ./tests.jsonl --config ./agents/agent.yaml --out ./eval_results.jsonl

---

Config Helpers

agentik config path

Show the .agentikrc path for a scope.

PowerShell

agentik config path --global
agentik config path --local

macOS/Linux

agentik config path --global
agentik config path --local

---

Built‑in Tools & Policies

Selected built‑ins:

• http_fetch(url, ttl, timeout, max_bytes, headers, allow_network) → {ok, data, error, meta} (data.text, data.status, cache info)
• html_to_text(html, keep_newlines, drop_links, max_chars) → plaintext
• write_file(path, content, encoding, overwrite, allow_abs, allow_filesystem) → safe file writer

Policies are enforced by config:

policies:
  allow_network: true | false
  allow_filesystem: true | false

If a tool requires a disabled capability, the call is blocked and recorded in observations/transcripts.

---

Transcripts & Cost Estimation

Add --save-transcript PATH (single run) or --save-transcripts DIR (dev watch) to write JSONL transcripts. Summaries include steps, token counts, timings, and cost if available.

Optional pricing overrides (USD / 1K tokens):

PowerShell

$env:AGENTIK_PRICE_PROMPT_PER_1K = "0.50"
$env:AGENTIK_PRICE_COMPLETION_PER_1K = "1.50"

macOS/Linux

export AGENTIK_PRICE_PROMPT_PER_1K="0.50"
export AGENTIK_PRICE_COMPLETION_PER_1K="1.50"

---

Quick Reference Table

---

You’re set. Keep this open while you iterate; pair it with agentik dev watch for the fastest edit‑run loop.

---

Troubleshooting

• “Network error talking to OpenRouter.” Confirm your key in the current shell:

  • PowerShell: echo $env:OPENROUTER_API_KEY
  • macOS/Linux: echo $OPENROUTER_API_KEY Then try: agentik models list --refresh. Behind a proxy? Set HTTP_PROXY/HTTPS_PROXY.

• Dev watcher: “unexpected extra arguments …”

  • Quote globs in PowerShell: --include '**/*.py' (single quotes).

• Auth error / missing key: set OPENROUTER_API_KEY or run agentik keys set openrouter ....

• Rate limited: add delays, batch, or upgrade your OpenRouter plan.

• Network error: check connectivity or proxy settings (HTTP_PROXY, HTTPS_PROXY).

• PowerShell globbing: quote globs, e.g. --include '**/*.py'.

---

Development

• Lint/format: ruff check . and black .
• Tests: pytest -q

---

Happy building with Agentik!