From Plans to Agents.
A unified AI runtime for Loquent.

§1Context — why we're doing this

Loquent's AI capabilities live in eight disconnected places. Each has its own prompt-building, model resolution, tool list, logging shape, notification path, and permission story. There is no shared identity an end user can name, configure, or watch evolve.

What an org owner experiences today

They see a dashboard briefing, a daily report email, three reply suggestions on every inbound message, and (if they're using campaigns) a Plan timeline. None of those four AI surfaces are aware of each other. The dashboard briefing doesn't know the campaign agent has been pestering a contact about something specific. The text-reply suggestions don't know what the daily report told the owner this morning.

What we want them to experience

One mental model: "These are my agents. They have personalities, they follow rules I taught them, and they're learning from how I use them." Concretely:

• One identity per agent (org-scoped, kind-tagged, persona on file)
• One timeline showing every operation, with cost and latency per step
• One rule system where platform rules layer under org rules layer under per-agent rules
• One memory attribution: every contact note knows which agent and which run wrote it
• One learning loop: daily reflections → weekly skills → monthly distillation

§2Research summary

2.1 Hermes Agent — the source of inspiration

You mentioned Hermes Agent as the model. The reference is Nous Research's Hermes Agent — a self-improving multi-agent framework where every agent is a profile: a fully isolated unit with its own configuration, persona (SOUL.md), memory database, tool list, and cron jobs. Profiles connect independently to Telegram, Discord, Slack, WhatsApp, Signal, Email. Each is a complete CLI entity with its own personality.

2.2 Agent anatomy across modern frameworks

No framework has built-in multi-tenant access control or organization-scoped rules. Loquent has to design this layer itself.

2.3 Self-evolution — three mechanisms we'll blend

2.4 Observability — OpenTelemetry GenAI conventions

Since 2024, OpenTelemetry has defined semantic conventions for GenAI tracing. This is the emerging industry standard that unifies Langfuse, LangSmith, Helicone, Traceloop. We adopt it in ai_agent_log day one so a future export to any tracing backend is a config change, not a refactor.

§3Current state in Loquent

Three modules already do most of what we need. They just don't know about each other.

The Plan system — already 90% an agent runtime

src/mods/plan/ (71 file references) is a sophisticated autonomous-execution framework. It has a typed tool-call log, an 8-state JSONB state machine, a cron-polled executor, contact assignments, autopilot gating, approval gates, re-enrollment policy, per-template model override. The hard problems are solved here.

The 8 plan states (we reuse this exact shape for AiAgentRunState)

The 13 typed tool variants (we keep this typed-per-kind pattern)

SendEmail, SendSms, ListPlanContacts, GetContactDetails, GetContactNotes, WriteInteractionNote, UpdateSystemNote, GetConversationHistory, UpdateContact, AskUser, CompletePlan, FailPlan, ScheduleNextExecution

The Text Agent — already a separate module

src/mods/text_agent/ generates 3 high/med/low-confidence reply suggestions per inbound message. Has its own text_agent table (purpose, tier, model, escalation_instructions, restricted_topics, temperature, knowledge_base_ids) and a text_agent_suggestion table. Critical-path code: generate_text_agent_suggestions_service.rs:11.

The Voice Agent — naming collision risk

The AI infrastructure — already well-organized

src/mods/ai/ wraps aisdk + OpenRouter. The ai_usage_log table + spawn_log_ai_usage(AiUsageEntry) helper at log_ai_usage_service.rs:13 capture every AI call's tokens, cost, model, provider, latency. 26 AiUsageFeature variants already cover every call site (TextAgentSuggestions, DashboardBriefing, AnalyzeCall, SummarizeCall, UpdateContactMemory, GenerateReport, ExtractTasks, RealtimeTurn, …).

§4Target architecture

The 6 dimensions of an AiAgent

Agent kinds — the launch lineup

Naming: internal vs. UI

• Internal (Rust code): AiAgent, mods::ai_agent, ai_agent table, AiAgentResource permission. Disambiguates from existing voice Agent.
• User-facing (UI copy): "Agents" everywhere. Voice agents become "Voice Agents". Owners see one mental model.

§5Data model

10 new tables. 4 existing tables augmented with nullable FKs. No drops in the migration window.

ER diagram

The big four — what they store, why they exist

1. ai_agent — the identity (the SOUL.md row)

One row per agent. Org-scoped. Holds: kind, name, slug, is_system_default, is_active; JSONB fields for persona (tone/voice/signature/traits/soul_md), goals, rules_override, tools_allowlist, access_scope, budget; plus model_override, enable_reflection, enable_autopilot.

Indexes: (organization_id, kind, slug) UNIQUE; (kind) for dispatch fan-out; partial on active rows.

2. ai_agent_run — one execution

Has state (the AiAgentRunState enum JSONB, same shape as PlanState), parent_run_id for orchestration chains, trigger_source JSONB (Manual { user_id } | Cron { schedule_id } | Webhook { entity, entity_id } | Triggered { by_run_id }), input_payload, output_payload, total cost/tokens/tool-calls, and trace_id for OTel.

3. ai_agent_log — unified, OTel-compatible timeline

The single most important new table. Every operation an agent performs becomes one row. Six kinds:

Indexes for fast analysis AND reflection pipeline: (ai_agent_run_id, created_at) primary for timeline rendering; (ai_agent_id, created_at DESC) for "recent activity"; (organization_id, created_at DESC) partial on llm_generation|tool_call for cost dashboards; GIN on entry for JSONB attribute search.

4. ai_agent_schedule — cron-driven runs

One row per scheduled agent. cron_spec + timezone + next_run_at + is_enabled + config_payload JSONB (recipients, filters — kind-specific). A single run_due_ai_agents_job polls every minute with SELECT … FOR UPDATE SKIP LOCKED and dispatches.

The evolution tables (Phase 9)

System rules

platform_ai_rule — system-wide immutable rules (slug, applies_to_kinds JSONB, rule_text, priority). Edited only by code-reviewed migrations. The existing organization_ai_rule table becomes the org tier.

§6Migration phases

Eleven phases. The first ships in a week with zero behavior change. The next three retarget existing modules. Phase 4 attaches Plans to the new runtime structurally without changing the executor.

1. PHASE 0 Foundations

   M · 1 week · first PR

   Land ai_agent, ai_agent_run, ai_agent_log tables + Rust types + generic run_ai_agent executor + admin-only debug endpoint. Zero behavior change. Adds the AiAgent permission resource.

2. PHASE 1 Dashboard Briefing Agent (pilot)

   M · lowest blast radius

   Retarget generate_dashboard_briefing_service to run via the new runtime. Failures are cosmetic (stale briefing) — perfect first pilot. Per-org flag, A/B parity test, hard token budget.

3. PHASE 2 Text Reply Agent

   L · structured output

   Refactor mods::text_agent to back its persona/rules on ai_agent. Critical path (every inbound message). Auto-fallback to legacy on schema parse failure. 10% rollout watched for a week before 100%.

4. PHASE 3 Custom Report Agent + schedule dispatcher

   L · cron consolidation

   Replace SendDailyReportJob with RunDueAiAgentsJob driven by ai_agent_schedule. Mutually-exclusive flags prevent duplicate sends. 7-day shadow-run before cutover.

5. PHASE 4 Autonomous Campaign Agent (attach plans)

   XL · structural only

   Every plan + plan_template gets an ai_agent_id FK (kind=AutonomousCampaignAgent). Plan log dual-writes to ai_agent_log. Executor body unchanged. Plans-specific bookkeeping (contacts, actions, re-enrollment) stays where it is.

6. PHASE 5 Seed default agents on signup

   S · 2–3 days

   New seed_default_agents_service called from finalize_signup_service:174. Creates DashboardBriefing + CustomReport agents. Non-blocking like existing notification-pref seeder.

7. PHASE 6 Layered rules (Platform > Org > Agent)

   M

   3-tier rule injection via build_layered_rules. Platform rules immutable; ship via code-reviewed migration. Every run snapshots effective rules in its log for auditability.

8. PHASE 7 Memory unification

   M

   All contact-memory writes stamped with ai_agent_run_id. New ai_agent_memory table for short-term scratchpad + long-term facts. pgvector deferred (JSONB + GIN until proven needed).

9. PHASE 8 Onboard remaining AI ops

   XL · 6 small PRs · parallelizable

   One PR per kind: AnalyzerAgent, TaskExtractionAgent, AutoTagAgent, ContactEnrichmentAgent, ContactMemoryAgent (messages batch), AssistantAgent. Each is a drop-in replacement of the inline aisdk call.

10. PHASE 9 Self-evolution pipeline

    XL · opt-in

    Daily/weekly/monthly reflection cron + skill extraction (Voyager) + lesson capture (Reflexion). ReflectionAgent kind. UI at /agents/{id}/evolution. Opt-in per org due to cost.

11. PHASE 10 Budgets, throttling, observability UI

    L

    Per-agent + per-org budget enforcement before every LLM call. Unified timeline view at /agents/{id}/runs/{run_id}. Cost/latency/success-rate metrics dashboard.

12. PHASE 11 Voice agent rename (optional, late)

    L · mechanical

    Resolve long-term collision: Agent → VoiceAgent. Only after the new runtime is stable for ≥6 months. Pure rename PR with cargo check guardrails.

Top 5 risks & mitigations

§7Observability — tracing every operation

Every thought, tool call, LLM generation, and system event becomes one indexed row in ai_agent_log. Optimized for fast timeline rendering AND for feeding the reflection pipeline.

The indexes that matter

§8Self-evolution — the learning loop

The loop closes when build_ai_agent_prompt_service retrieves the top-K relevant skills + recent lessons and injects them into the next run's prompt. Voyager pattern: agents get better at the same task family over time, without retraining.

Cost discipline

• Opt-in per org with a 14-day free trial. Default off.
• Cheapest available model for reflection (e.g. deepseek-v3.2).
• Hard per-agent monthly token budget enforced.
• Skills with failure rate > threshold are auto-disabled.
• Weekly distillation re-evaluates daily reflections (averaging effect against bad-day reinforcement).

Admin curation

The owner can view /agents/{id}/evolution: every reflection, every extracted skill (with success/failure counts), every lesson. They can edit, suppress, or retire any of them. This keeps the loop transparent — agents that learn must also be agents you can teach.

§9The three initial agents (Phase 1–3 deliverables)

§10Org onboarding — defaults on signup

Hook added to finalize_signup_service.rs:174, right beside the existing notification-preference seeding. The new seed_default_agents creates:

• 1× DashboardBriefingAgent per org — system default, active, autopilot
• 1× CustomReportAgent per org — system default, active, daily 5 AM schedule
• 1× TextReplyAgent per phone number provisioned — autopilot=false (suggestions, not auto-replies)

Each seeded agent carries is_system_default = true. The org admin can edit any of these. Setting is_system_default = false orphans the row from future platform updates — so a platform-level persona update doesn't overwrite a customer's edits.

§11Layered rules — system > org > agent

Three layers concatenated into every agent's system prompt. Platform rules are immutable from any UI; they ship via code-reviewed migration.

Example platform rules (immutable)

• Never make legal, medical, or financial advice claims.
• Never share PII outside the org boundary.
• Always announce when a message is AI-generated if asked.
• Never autopilot a destructive action without explicit org-owner approval.
• Always log every tool call with full input/output.

Example org rules (editable)

• Sign messages as "Alex from Acme Co."
• Use first-name only when addressing contacts.
• Never discuss competitor X.

Example agent rules (per-agent overrides)

• This text agent only handles inbound questions about pricing.
• This report agent emails the founder, not the team.

§12Verification plan

How we know each phase is safe to ship.

End-to-end smoke (after Phase 5)

1. Sign up a new org
2. Provision a phone number
3. Observe DashboardBriefing + CustomReport + TextReply agents created
4. Send an SMS to the phone number → observe 3 suggestions generated via new path
5. Wait for daily report cron tick → observe email delivered
6. Open dashboard → observe briefing rendered
7. Inspect /agents/{id}/runs/{run_id} timeline for each
8. Confirm ai_usage_log rows have matching ai_agent_log rows

§13Open questions for you

These are the decisions where multiple reasonable answers exist. Recommended option is highlighted. Please confirm or redirect.

§14References

Primary sources used in this research.

1. Hermes Agent — Nous Research · Profiles
2. Generative Agents — Park et al., Stanford/Google (UIST '23)
3. Reflexion: Language Agents with Verbal Reinforcement Learning — Shinn et al. (NeurIPS 2023)
4. Voyager: Open-Ended Embodied Agent with LLMs — Wang et al. (2023)
5. Anthropic — Building Effective Agents (Dec 2024)
6. CrewAI Documentation — Agents & Memory
7. Letta (MemGPT) — Agent Memory
8. OpenTelemetry GenAI Semantic Conventions
9. Langfuse — Open-Source LLM Observability
10. Policy-as-Prompt — arXiv:2509.23994