# Fetch the Linux x86_64 artifact
curl -LO https://releases.agent-framework.io/v0.3.1/agent-runtime-x86_64-linux.tar.gz

# Extract and place in execution path
tar -xzf agent-runtime-x86_64-linux.tar.gz
sudo mv agent-cli agent-daemon /usr/local/bin/

# Verify installation integrity
agent-cli --version
# Expected: agent-cli 0.3.1

cargo install agent-cli agent-daemon --locked

# ~/.agent-runtime/secrets.env
PROVIDER_AUTH_TOKEN=sk-ty-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# ~/.agent-runtime/operational.yaml
runtime:
  provider_alias

: vllm_compatible endpoint: https://api.opentyphoon.ai/v1 model_identifier: typhoon-v2.1-12b-instruct

context: max_tokens: 8192 compression: active: true trigger_ratio: 0.65 strategy: semantic_trim

memory: persistence_path: ~/.agent-runtime/storage/facts/ compaction_cycle: 5 session_db: ~/.agent-runtime/storage/sessions.db

**Architectural Rationale:**
- `provider_alias: vllm_compatible` maps to the OpenAI chat completion schema. Typhoon’s endpoint adheres to this standard, allowing zero-code adapter logic.
- `trigger_ratio: 0.65` initiates context compression when 65% of the window is consumed. This preserves recent turns while summarizing older interactions, preventing abrupt truncation.
- `compaction_cycle: 5` extracts factual statements every five interaction turns and writes them to persistent storage. This creates a searchable knowledge graph without external dependencies.

### Step 4: Diagnostic Validation

Before entering production loops, validate endpoint reachability, credential injection, and storage initialization.

```bash
agent-cli validate-stack

Expected output confirms successful routing:

✓ Configuration loaded     alias=vllm_compatible  model=typhoon-v2.1-12b-instruct
✓ Credential resolved      PROVIDER_AUTH_TOKEN present
✓ Endpoint reachable       https://api.opentyphoon.ai/v1 → 200 OK
✓ Storage initialized      ~/.agent-runtime/storage/facts/ (0 entries)
✓ Session database ready   ~/.agent-runtime/storage/sessions.db

Step 5: Execution Modes

The runtime supports interactive, batch, and scheduled execution. Each mode shares the same memory layer and context window.

Interactive TUI:

agent-cli interactive

Batch invocation:

agent-cli run "สรุปจุดแข็งจุดอ่อนของการจดทะเบียนบริษัทจำกัดในประเทศไทย"

Scheduled automation:

# Inject into environment
AGENT_CRON_SCHEDULE="0 8 * * *=ค้นหาข่าวเศรษฐกิจไทยล่าสุด สรุป 5 ประเด็นหลัก บันทึกที่ ~/daily-brief.md"
agent-daemon start

Pitfall Guide

1. Context Window Saturation in Long Conversations

Explanation: Multi-turn loops gradually consume the token budget. Without compression, the runtime silently drops early turns, causing loss of critical instructions or user preferences. Fix: Enable semantic compression with a trigger_ratio between 0.60 and 0.70. Monitor token consumption via runtime logs and adjust the ratio based on conversation density.

2. Silent Rate Limit Degradation

Explanation: The free tier enforces 5 req/s and 200 req/min. Burst requests trigger HTTP 429 responses. While the runtime includes automatic retry logic, aggressive polling degrades throughput and increases latency. Fix: Implement client-side request queuing. Batch non-urgent calls and respect the Retry-After header. For enterprise workloads, migrate to the production API (planned for AWS deployment in 2026).

3. Memory Fragmentation Across Sessions

Explanation: Persistent memory stores facts as discrete entries. Over time, redundant or contradictory statements accumulate, causing the agent to reference outdated preferences. Fix: Schedule periodic memory compaction. Use the compaction_cycle parameter to trigger deduplication. Manually prune stale entries via agent-cli memory prune --older-than 30d.

4. Tool Invocation Ambiguity

Explanation: Smaller models (12B) may skip tool calls when instructions are vague. The agent defaults to text generation instead of executing file reads, web searches, or API calls. Fix: Explicitly declare tool requirements in the prompt. Example: ใช้เครื่องมือ web_search เพื่อค้นหา... If ambiguity persists, switch to typhoon-v2.5-30b-a3b-instruct for complex reasoning chains.

5. Hardcoded Language Fallbacks

Explanation: Developers sometimes force English output by embedding system prompts that override the model’s native tokenization. This degrades Thai syntactic alignment and increases token cost. Fix: Rely on the memory layer to enforce language preferences. Issue a single instruction: ตอบเป็นภาษาไทยเสมอ The runtime persists this rule across sessions without prompt injection.

6. Credential Exposure in Logs

Explanation: Debug modes may echo full HTTP headers, including authorization tokens. Automated log aggregation pipelines can inadvertently expose secrets. Fix: Disable verbose logging in production. Use the runtime’s built-in secret masking feature. Rotate PROVIDER_AUTH_TOKEN immediately if exposure is suspected.

7. Context Window Mismatch on Model Swap

Explanation: Switching from the 12B to the 30B variant without updating max_tokens causes silent truncation or API rejection. The 30B model supports a 32,768 token window. Fix: Always pair model switches with context window updates. Validate via agent-cli validate-stack after configuration changes.

Production Bundle

Action Checklist

• Verify binary integrity and runtime version before deployment
• Isolate credentials in a non-version-controlled environment file
• Configure compression trigger ratio between 0.60 and 0.70
• Set compaction cycle to 5 turns for balanced memory retention
• Validate endpoint reachability and credential injection via diagnostic command
• Implement client-side request queuing to respect rate limits
• Schedule periodic memory pruning to prevent fragmentation
• Test tool invocation clarity before deploying to customer-facing loops

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-frequency customer support	typhoon-v2.1-12b-instruct + compression	Lower latency, sufficient reasoning for standard queries	Free tier covers ~200 req/min; minimal infrastructure cost
Contract analysis / multi-step planning	typhoon-v2.5-30b-a3b-instruct + 32k context	Superior logical chaining and document parsing	Same rate limits; higher token consumption per request
Edge deployment / CI integration	Precompiled Rust binary + local memory	Sub-20ms cold start, zero dependency resolution	No container runtime or orchestration overhead
Enterprise-scale automation	Migrate to production API (2026 AWS)	Guaranteed throughput, SLA-backed rate limits	Commercial licensing; predictable per-token pricing

Configuration Template

# ~/.agent-runtime/operational.yaml
runtime:
  provider_alias: vllm_compatible
  endpoint: https://api.opentyphoon.ai/v1
  model_identifier: typhoon-v2.1-12b-instruct

context:
  max_tokens: 8192
  compression:
    active: true
    trigger_ratio: 0.65
    strategy: semantic_trim

memory:
  persistence_path: ~/.agent-runtime/storage/facts/
  compaction_cycle: 5
  session_db: ~/.agent-runtime/storage/sessions.db

logging:
  level: warn
  mask_secrets: true

# ~/.agent-runtime/secrets.env
PROVIDER_AUTH_TOKEN=sk-ty-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quick Start Guide

1. Download & Install: Fetch the architecture-specific binary, extract it, and move agent-cli and agent-daemon to your system path. Verify with agent-cli --version.
2. Configure Credentials: Create ~/.agent-runtime/secrets.env and populate PROVIDER_AUTH_TOKEN with your Typhoon API key. Ensure file permissions restrict read access to the owner.
3. Deploy Configuration: Copy the configuration template to ~/.agent-runtime/operational.yaml. Adjust model_identifier and max_tokens if switching to the 30B variant.
4. Validate Stack: Run agent-cli validate-stack. Confirm all checks return green. Resolve any credential or endpoint errors before proceeding.
5. Execute First Loop: Launch agent-cli interactive or run a batch command. Issue a language preference instruction once. The runtime will persist it across all future sessions.