01. Getting Started with euleragent — Workspace Setup and First Run

Learning Objectives

By the end of this tutorial, you will be able to:

Install euleragent and verify its status
Initialize a workspace and understand its directory structure
Create an agent and understand the agent.yaml file
Run your first task and read the results
Check the approval list and batch accept approvals
Track execution history through the audit log

Prerequisites

Item	Version / Requirement
Python	3.11 or higher
pip	Latest recommended
euleragent	Install from source with `pip install -e .`
Ollama	Running (or use `default_llm_profile: fake`)

This tutorial assumes you have the euleragent source code locally. If you haven't cloned it yet:

git clone https://github.com/your-org/euleragent.git
cd euleragent

Step-by-Step Guide

Step 0: (Recommended) Isolate Python Environment with venv

In Python projects, it is common practice to create a virtual environment (venv) to isolate dependencies (pip packages) and the runtime environment per project. This prevents conflicts with the system Python or packages from other projects, allowing you to safely install libraries needed only for this workspace.

euleragent follows the same standard practice: create a .venv/ in the workspace (working directory), activate that environment, then install and run.

Example (from the workspace directory):

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

Step 1: Install euleragent

Install in editable mode from the project root directory. This approach allows changes to the source code to take effect immediately without reinstalling.

pip install -e .

Once installation is complete, the euleragent command will be registered in your PATH:

euleragent --version

Expected output:

euleragent 0.1.x

Step 2: View Help

Use the --help flag to see all available commands and options:

euleragent --help

Expected output:

Usage: euleragent [OPTIONS] COMMAND [ARGS]...

  euleragent — local-first CLI agent creation and execution framework.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  approve   Manage approval queue (list, show, accept, reject)
  chat      Interactive chat with an agent
  doctor    Run environment health check
  init      Initialize a new workspace
  logs      Show audit log for a run
  memory    Manage long-term memory
  new       Scaffold a new agent from a template
  rag       Manage local knowledge base (RAG)
  run       Run an agent with a task
  workflow  Manage dynamic workflows

Step 3: Run Environment Diagnostics

The doctor command diagnoses whether euleragent is working correctly. It can be run even if no workspace exists in the current directory.

euleragent doctor

Expected output:

euleragent doctor
  [OK] Python 3.11.x
  [OK] euleragent 0.1.x installed
  [OK] Workspace: /home/user/my-project/.euleragent
  [OK] Config: workspace.yaml found
  [WARN] Ollama: not reachable at http://localhost:11434
         Set default_llm_profile: fake in workspace.yaml for offline testing
  [OK] Memory: SQLite enabled
  [OK] Approvals directory: .euleragent/approvals/

Tip: You can proceed with the tutorials even if Ollama is not running. Setting default_llm_profile: fake in workspace.yaml allows you to test the entire flow without an LLM.

Step 4: Initialize a Workspace

Create a new project directory and initialize the workspace.

mkdir ~/my-project && cd ~/my-project
euleragent init

Expected output:

Workspace initialized at /home/user/my-project/.euleragent
  Created: .euleragent/config/workspace.yaml
  Created: .euleragent/config/company_brief.md
  Created: .euleragent/agents/
  Created: .euleragent/runs/
  Created: .euleragent/approvals/
  Created: .euleragent/projects/
  Created: .euleragent/state/

Verify the generated directory structure:

ls -la .euleragent/

.euleragent/
├── config/
│   ├── workspace.yaml      # Global configuration file
│   └── company_brief.md    # Company/team context (optional)
├── agents/                 # Agent configuration directory
├── runs/                   # Execution records (subdirectories per run_id)
├── approvals/              # HITL approval queue (JSONL files)
├── projects/               # Per-project context
└── state/
    └── memory.db           # Long-term memory SQLite DB (created after first conversation)

Review the default contents of workspace.yaml:

cat .euleragent/config/workspace.yaml

# euleragent workspace configuration
# Generated by `euleragent init`. Edit freely — comments are preserved.
version: 1

llm_profiles:
  local:
    provider: ollama
    base_url: http://localhost:11434
    model: qwen3:32b
    timeout_seconds: 120
    keep_alive: "5m"
    is_external: false

  openai:
    provider: openai
    api_key: ""
    model: gpt-4o-mini
    base_url: https://api.openai.com/v1
    is_external: true

  # --- Gemini via OpenAI-compatible endpoint (uncomment to enable) ---
  # gemini:
  #   provider: openai_compat
  #   api_key: ""
  #   model: gemini-2.0-flash
  #   base_url: https://generativelanguage.googleapis.com/v1beta/openai
  #   is_external: true

default_llm_profile: local

# ... (budget, policy, memory, tools_policy, rag sections) ...

mcp:
  enabled: false
  servers: []
  # --- Uncomment below to add MCP servers ---
  # servers:
  #   - id: demo_sqlite
  #     url: http://localhost:9020/mcp
  #     allow_tools: [sqlite.query, demo.echo]

When using Ollama: The default is default_llm_profile: local, so make sure Ollama is running (ollama serve). For offline testing, change to default_llm_profile: fake.

Tip: workspace.yaml includes commented examples for a Gemini profile and MCP server. - Using Gemini: Uncomment the # gemini: block and set your GEMINI_API_KEY. - Using OpenAI: Enter your API key in openai.api_key and change to default_llm_profile: openai. - Connecting MCP servers: Uncomment the servers: section under mcp:. The demo server can be launched with python examples/mcp/sqlite_tools_server.py.

Step 5: Create an Agent

Use the euleragent new command to create an agent from a predefined template. There are 4 available templates: personal-assistant, marketing-expert, code-assistant, and ops-assistant.

euleragent new my-assistant --template personal-assistant

Expected output:

Agent 'my-assistant' created at .euleragent/agents/my-assistant
  Files:
    agent.yaml
    tools.yaml
    prompts/system.md
    prompts/output_templates.md

Review the generated agent files:

cat .euleragent/agents/my-assistant/agent.yaml

name: my-assistant
description: "Personal assistant for daily tasks and information lookup"
template: personal-assistant
version: "1.0"

memory:
  enabled: true
  retrieval:
    top_k: 5
    min_score: 0.2

provider: null                  # If null, uses default_llm_profile from workspace.yaml
model: null                     # If null, uses the profile's default model

tools_denylist: []              # Tools to block for this agent only

Also check tools.yaml:

cat .euleragent/agents/my-assistant/tools.yaml

policy: deny-all                # All tools not on the explicit allowlist are blocked
allowlist:
  - file.read
  - file.write
  - memory.store
  - memory.search
require_approval:
  - file.write
  - file.delete
  - shell.exec
  - web.search
  - web.fetch
  - email.send

deny-all principle: policy: deny-all is a core security design of euleragent. Only tools listed in the allowlist can be used by the agent. Tools on the require_approval list require human approval before execution.

Step 6: Run Your First Task (Plan Mode)

Now run the agent. The default mode is plan, where the agent proposes what actions to take and waits for human approval before actual execution.

euleragent run my-assistant \
  --task "AI 에이전트 프레임워크를 3줄로 요약해줘" \
  --mode plan

Expected output:

Run a1b2c3d4e5f6 started (agent: my-assistant, mode: plan)
  Task: AI 에이전트 프레임워크를 3줄로 요약해줘

[loop 1/5] Generating plan...
  → No tool calls proposed (text response only)

Run a1b2c3d4e5f6 completed (state: RUN_FINALIZED)
Artifacts:
  .euleragent/runs/a1b2c3d4e5f6/artifacts/plan.md

0 approval(s) pending.

Note: In this example, the agent returned only text without any tool calls. Scenarios involving tool calls are covered in the next step.

Review the generated artifact:

cat .euleragent/runs/a1b2c3d4e5f6/artifacts/plan.md

## AI 에이전트 프레임워크 요약

1. AI 에이전트 프레임워크는 LLM이 도구(tool)를 호출해 실제 작업을 수행할 수 있도록 하는 오케스트레이션 레이어입니다.
2. 주요 프레임워크로는 LangChain, CrewAI, AutoGen, euleragent 등이 있으며, 각각 멀티 에이전트 협력, 반복 루프, 승인 게이트에서 차별화됩니다.
3. euleragent는 로컬 우선(local-first), HITL 승인, 감사 로그를 핵심 원칙으로 삼는 프레임워크입니다.

Step 7: Run a Task with Tool Calls

Run a task that uses the file.write tool to experience the approval flow:

euleragent run my-assistant \
  --task "summary.md 파일을 만들고 AI 에이전트 프레임워크를 3줄로 요약해서 저장해줘" \
  --mode plan

Expected output:

Run b2c3d4e5f6a1 started (agent: my-assistant, mode: plan)
  Task: summary.md 파일을 만들고 AI 에이전트 프레임워크를 3줄로 요약해서 저장해줘

[loop 1/5] Generating plan...
  → Proposed: file.write (risk: medium)

Run b2c3d4e5f6a1 completed (state: PENDING_APPROVAL)

1 approval(s) pending. Use `euleragent approve list --run-id b2c3d4e5f6a1`

The PENDING_APPROVAL state means the agent proposed a tool call that requires approval and is waiting for human review.

Step 8: Check the Approval List

euleragent approve list

Expected output:

Pending approvals (1):

  ID              TOOL         RISK    RUN              STATUS
  apv_x1y2z3      file.write   medium  b2c3d4e5f6a1     pending

To filter approvals for a specific run:

euleragent approve list --run-id b2c3d4e5f6a1

View approval details:

euleragent approve show apv_x1y2z3

Expected output:

{
  "id": "apv_x1y2z3",
  "run_id": "b2c3d4e5f6a1",
  "tool_name": "file.write",
  "params": {
    "path": "summary.md",
    "content": "## AI 에이전트 프레임워크 요약\n\n1. AI 에이전트 프레임워크..."
  },
  "risk_level": "medium",
  "status": "pending",
  "created_at": "2026-02-23T10:30:00Z"
}

Step 9: Batch Approve and Execute

After reviewing the approval details, accept all pending approvals and execute immediately:

euleragent approve accept-all --run-id b2c3d4e5f6a1 --actor "user:you" --execute

Expected output:

Accepted 1 approval(s).
  [OK] file.write (apv_x1y2z3)
Executed 1/1 successfully.

Run b2c3d4e5f6a1 state: RUN_FINALIZED
Artifacts:
  .euleragent/runs/b2c3d4e5f6a1/artifacts/plan.md
  summary.md  ← Actual file created

Verify the file was actually created:

cat summary.md

Step 10: Read the Audit Log

Detailed logs for all runs can be viewed with the euleragent logs command:

euleragent logs b2c3d4e5f6a1

Expected output:

Run: b2c3d4e5f6a1
  Agent:   my-assistant
  Task:    summary.md 파일을 만들고...
  Mode:    plan
  State:   RUN_FINALIZED
  Started: 2026-02-23 10:30:00
  Ended:   2026-02-23 10:30:45

Events:
  10:30:00  run.started
  10:30:02  loop.started (1/5)
  10:30:04  tool.proposed  file.write → apv_x1y2z3
  10:30:05  loop.ended
  10:30:05  run.pending_approval
  10:30:30  approval.accepted  apv_x1y2z3
  10:30:31  tool.executed  file.write → OK
  10:30:31  run.finalized

To output in JSON format:

euleragent logs b2c3d4e5f6a1 --format json

You can also explore the run directory directly:

ls .euleragent/runs/b2c3d4e5f6a1/

input.json          # Execution input parameters
messages.jsonl      # Complete LLM conversation history
tool_calls.jsonl    # Tool call records
approvals.jsonl     # Approval records
artifacts/          # Generated files
diffs/              # File change diffs (when applicable)

Expected Output Summary

A summary of each command's results from this tutorial:

# Installation
$ euleragent --version
euleragent 0.1.x

# Diagnostics
$ euleragent doctor
  [OK] Python 3.11.x  [OK] euleragent installed ...

# Initialization
$ euleragent init
Workspace initialized at /home/user/my-project/.euleragent

# Agent creation
$ euleragent new my-assistant --template personal-assistant
Agent 'my-assistant' created at .euleragent/agents/my-assistant

# Run (no tool calls)
$ euleragent run my-assistant --task "..." --mode plan
Run a1b2c3d4e5f6 completed (state: RUN_FINALIZED)
0 approval(s) pending.

# Run (with tool calls)
$ euleragent run my-assistant --task "..." --mode plan
Run b2c3d4e5f6a1 completed (state: PENDING_APPROVAL)
1 approval(s) pending.

# Batch approve + execute
$ euleragent approve accept-all --run-id b2c3d4e5f6a1 --actor "user:you" --execute
Accepted 1 approval(s). Executed 1/1 successfully.

# Audit log
$ euleragent logs b2c3d4e5f6a1
Run: b2c3d4e5f6a1 ... State: RUN_FINALIZED

FAQ / Common Errors

Q: I get a euleragent: command not found error.

This occurs when pip install -e . has not completed, or the script installation path is not in your PATH.

# Check pip installation location
pip show euleragent | grep Location

# Typically ~/.local/bin should be in your PATH
echo $PATH | grep -o '[^:]*local[^:]*'

# If not in PATH, add it to .bashrc or .zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Q: euleragent doctor says Ollama is not reachable.

You can test all functionality with the fake provider even without Ollama:

# .euleragent/config/workspace.yaml
default_llm_profile: fake

To use an actual LLM:

ollama serve          # Keep running in terminal 1
ollama pull qwen3:8b  # Download model (first time only)

Q: What happens if I run euleragent init when a workspace already exists?

It does not overwrite existing configuration files. Files that already exist are left untouched, and only missing files are created. It is safe to re-run.

Q: What happens if I don't approve after euleragent run returns PENDING_APPROVAL?

Approval records are permanently stored in the .euleragent/approvals/ directory. You can review and process them at any time later with euleragent approve list. The pending approval state persists even after a system restart.

Q: What is the difference between --mode plan and --mode execute?

plan: The agent only proposes which tools to use and how, and actual execution happens after human approval.
execute: Tools that don't require approval are executed immediately. Tools on the require_approval list still require approval.

For details, see 02_plan_execute_mode.md.

Q: Can I create a workspace at a different path using the --path option?

euleragent init --path /tmp/test-workspace

Then run euleragent commands from that directory. euleragent searches upward from the current directory for .euleragent/.

Common Mistakes (Out-of-Order Steps)

Symptom	Cause	Fix
`Error: No euleragent workspace found.`	`euleragent init` not run	`euleragent init`
`Error: Agent 'X' not found.`	`euleragent new` not run	`euleragent new X --template personal-assistant`
`Error: No task provided.`	`--task` or `--task-file` missing	`euleragent run <agent> --task '...'`

Next step: 02_plan_execute_mode.md — Compare Plan mode and Execute mode and understand the agentic loop.