13 posts tagged with "AI Agent"

Ansina Just Got a Heart and a Brain​

Deliver three foundational systems that move Ansina from prototype toward a composable, enterprise-ready runtime: a formal Heart protocol, an autonomic tick loop, and a flexible, OpenAI-compatible Brain interface.

Heart: A Formal Runtime Protocol with MLX Support​

The new Heart runtime protocol (heart/runtime.py) formalizes how the agent signals intent and responds to runtime events, making behavior predictable and testable. A dedicated MLX adapter (heart/adapters/mlx.py) bridges the Heart to an external ML execution layer, and new heartbeat endpoints (api/routes/heart.py) give orchestration layers full visibility into runtime state, backed by comprehensive tests.

BrainProvider: Swap Models Without Touching Code​

The new BrainProvider abstraction (brain/provider.py) centralizes model invocation, retries, and selection logic. Paired with an OpenAI-compatible adapter (brain/adapters/openai_compat.py), Ansina now integrates with local models or any third-party provider speaking the OpenAI API standard — no code changes required. Configuration is fully exposed via settings and example files, so teams can switch providers as a configuration decision — a real step toward vendor flexibility and cost control at scale.

Autonomy: A Tick Loop That Keeps Agents Honest​

The new autonomic tick loop (heart/tick/loop.py) drives periodic decision cycles and lifecycle transitions automatically, keeping the agent running gracefully under partial failure. Decision logic, snapshots, and selection strategy are cleanly separated for easier auditing and replay. The loop integrates directly with Heart events and BrainProvider calls, making retries and pacing explicit and observable, with deterministic snapshots supporting reproducible debugging.

Developer Experience and Reliability​

This release also strengthens the foundation for teams building on Ansina: updated docs and architecture blueprints, a fuller dependency lockfile for build reproducibility, a tightened API and error surface for actionable telemetry, and extensive new unit tests across the codebase.

Why This Matters​

Ansina moves decisively toward a production-grade runtime: clear heartbeat contracts, a vendor-agnostic brain interface, and an autonomic loop that keeps agents moving even when components fail. This combination of reliability, interoperability, and configurability makes Ansina worth a closer look.

Onward — building agents with both heart and brain.

Laid the foundation: core infra, API, auth, persistence, CI, tests and docs — a production-minded M0 skeleton for Ansina.

Lead A focused engineering sweep to make Ansina reviewable and operable without any model code. The PR delivers a full infra baseline (packaging, config, logging already merged via #19), then adds REST endpoints, auth, persistence primitives, CI gates, testing conventions and docs scaffolding. All checks (unit + e2e, both OS legs) are green; branch is still a draft pending final author flip to "ready for review."

🚧 What this PR adds

• 🧩 REST: 🛣️ API skeleton and middleware (src/ansina/api/app.py, routes/health.py, middleware.py, exception_handlers.py) to standardize request/response flows.
• 🔐 Auth: 🪪 API authentication and public endpoints (src/ansina/api/auth.py) with tests to validate behavior.
• 💾 Persistence: 🧰 DB foundation, migrator and initial migration (src/ansina/storage/database.py, migrator.py, migrations/0001_init.sql).
• 📄 Docs & README: 📝 README rewrite and docs scaffolding (docs/architecture/blueprint.md) to explain architecture sections §3–§5.

⚙️ CI, tests, and quality gates

• 🧪 Tests: ✅ Unit + E2E tests added (tests/unit/*, tests/e2e/test_server.py) and a testing strategy that defines unit conventions + E2E build validation gate.
• 🔁 CI pipeline: 🛠️ .github/workflows/ci.yml implements unit and E2E jobs; both OS legs pass on CI.
• 🧹 Hygiene: ✨ pre-commit, Makefile, pyproject tweaks and .gitignore updates to keep developer UX smooth.

🧭 Engineering choices & tradeoffs

• ⚖️ Separation: Model code intentionally excluded — M0 focuses on stability, contracts, and reproducible ops before wiring inference.
• 🧪 Validation-first: E2E gate ensures the runnable artifact builds cleanly on multiple OS runners before merging downstream model work.
• 📚 Documented: Architecture blueprint and examples (ansina.example.toml) make onboarding and future design decisions explicit.

🔎 Files and signals worth scanning

• 🔁 CI + tests: .github/workflows/ci.yml, tests/e2e/test_server.py
• 🧭 API surface: src/ansina/api/app.py, auth.py, routes/health.py, readiness.py
• 🗄️ Storage: src/ansina/storage/database.py, migrator.py, migrations/0001_init.sql
• 📘 Docs: README.md, docs/architecture/blueprint.md

This was a foundation-first sprint: stable contracts, testable CI, and readable docs — readying Ansina for the next phase where model integration becomes a consumer of this platform.

Onward to M1 — wire the models once the infra is battle-tested.

Designing a lean, provable AI agent runtime built from the ground up on Python ≥ 3.14: introducing the architecture blueprint for Ansina.

Currently in its blueprint phase and moving rapidly toward initial implementation, Ansina focuses on a tight, deterministic core where every architectural choice serves operational control, high signal-to-noise ratio, and zero unnecessary bloat.

Here is an inside look at what Ansina brings to the table as it prepares to launch:

📐 Pure Hexagonal Architecture​

• Streamlined REST Surface: Exposes a clean, single internal FastAPI REST API with zero channel bloat or unnecessary gateway protocol overhead.
• Deliberate State Management: Starts with a minimal SQLite schema, growing persistence intentionally rather than accumulating hundreds of unmanaged state tables.
• Never-Throw Streaming Contracts: Features an ApiProvider port where streaming errors are returned synchronously as terminal stream events, guaranteeing predictable error paths.
• First-Class Redaction: Implements structured logging with redaction hardcoded into the formatting pipeline to ensure sensitive data is filtered before it hits disk.

🫀 The Dual-Model Core: Heart & Brain​

Ansina separates autonomic local liveness from remote cognitive reasoning to eliminate round-trip network hops for basic decisions:

• The Heart (In-Process Autonomic Loop):

• Uses an embedded ≤4B parameter model running natively in-process via MLX on Apple Silicon (with a llama-cpp-python fallback).

• Bounded strictly by an 8k context window to ensure optimal prompt performance.

• Drives an always-on tick loop tasked exclusively with deciding idle vs. act vs. escalate without network overhead.

• The Brain (Remote High-Reasoning):

• Connects to 35B+ parameter models via an OpenAI-compatible BrainProvider port for complex reasoning tasks.

🎯 Hardware Target & Testing Strategy​

• Hardware First: Optimized explicitly to run as an always-on engine on local Apple Silicon hardware (M4 Mac Mini, 16GB unified memory).
• Black-Box Verification: Uses an E2E test harness that spins up python -m ansina as an isolated subprocess, testing readiness, migrations, and auth strictly over HTTP.

The design is locked, the constraints are set, and implementation of M0 — Skeleton is about to begin.

Hook: We pivoted to a pragmatic architecture — single-agent A2A — while keeping the original tri-node design one uncomment away.

Lead: After end-to-end tests showed sub-agent → A2A is unreliable in OpenClaw, the team chose stability and observability over brittle enforcement. The result: main does cross-agent calls directly, tri-node is parked (preserved), MCP tooling added, and docs + tests updated.

🔁 Why we pivoted

• ⚠️ Sub-agent A2A break: tests showed a sub-agent cannot reliably drive another agent over A2A; the break is the sub-agent+cross-agent combination.
• 🔍 Practical trade: preserve the tri-node design, but avoid production fragility by routing A2A from main→main.
• ♻️ Preserve, not delete: tri-node config, prompts, and workspaces remain in-place as JSON5 comments and IDENTITY.tri-node.md (tag v0.1.0 = revival baseline).

🛠️ What changed (concrete)

• 🧭 Single-agent mode: both containers make main the working agent; when code is needed Researcher main curls Coder at http://coder:3000/a2a/tasks.
• 🗂️ JSON5 preservation: sub-agent entries commented in openclaw.json so revival is one uncomment away.
• 🧰 Local MCPs: added filesystem MCP for Coder and memory MCP for Researcher; tools surface as bundle-mcp:<server>__<tool>.
• 🧪 Orchestration + tests: index.js remained logic-identical (comments updated); tmux vm-bridge used for live runs and probes.

✅ What we validated

• 🔎 Spawn logs: live single-agent tasks showed spawn_count = 0 — no sub-agent spawn.
• ↔️ A2A round-trip: Researcher→Coder→Researcher worked in live tests (Coder logged payload, returned structured JSON, Researcher folded result.output).
• 🧰 MCP probe: openclaw mcp doctor files → files: ok; doctor memory → memory: ok; live tool calls returned expected results.
• ⚙️ Docs & artifacts: AGENTS.md + README updated, diffs and diffstat adjusted, IDENTITY.tri-node.md preserved, tag v0.1.0 recorded.

📌 Edge cases, constraints & next steps

• 🪪 Prompt hygiene: observed headless-output violations (narration prefixes, markdown fences) and a fallback self-write when Coder was down — these are prompt-enforcement issues to fix, not A2A plumbing failures.
• 🔁 Operational note: to pick up MCP config changes, restart the container (sudo podman restart) — do NOT use pm2 restart openclaw-gateway (it can orphan the gateway).
• 🛠️ Revival path: once OpenClaw fixes cross-agent delegation from sub-agents, simply uncomment JSON5 entries + swap IDENTITY.tri-node.md back to resume tri-node operation.
• 🚦 Next: tighten prompt enforcement, add CI smoke-tests for A2A round-trip, and monitor upstream OpenClaw fixes to evaluate revival.

Final: Practical pivots win — preserved the long-term design while shipping a robust, testable PoC for cross-agent work.

Engineering Resilient Multi-Agent Systems: Gateway WebSockets and Guardrail Enforcement​

Ripped out fragile CLI wrappers and replaced them with full-lifecycle Gateway WebSocket orchestration. Silent sub-agent drops are dead. We stress-test the architecture until it breaks, document the exact failure boundaries, and hardcode stability at the protocol level.

⚡ Gateway WebSocket Lifecycle Architecture

• Ditched the fire-and-forget child-process CLI execution that was silently dropping sub-agent responses.
• Engineered direct Gateway WebSocket state management (connect ➔ agent ➔ event subscription ➔ resume runId for final payload synthesis) for guaranteed completion tracking.

⚙️ Fleet Parity & Network-Level A2A Delegation

• Upgraded Coder to Phase 1 parity with Researcher: established orchestrator-only routing and unconstrained sub-agent tool execution (exec, web_fetch).
• Wired cross-agent A2A delegation: routed Researcher's reviewer to delegate code specs directly to Coder over the network (POST http://coder:3000/a2a/tasks).

🛡️ Orchestrator Guardrail Enforcement

• Hardcoded 3 deterministic control-flow rules in main/IDENTITY.md to kill early-termination failure modes:
• Atomic Handoffs: Enforced sessions_spawn(reviewer) and sessions_yield back-to-back in a single turn—zero orphaned processes.
• Truncation Routing: Forced raw forwarding of truncated executor output straight to review without prompt-level narrative repairs.
• Error Handling: Guaranteed atomic forwarding of executor error/empty states directly to the reviewer alongside the blueprint.

🔬 Empirical Testing & Reality-Driven Limitations

• Executed 5 rigorous end-to-end integration tests across the agent network.
• The Hard Reality: Proven that prompt-level negative constraints ("FORBIDDEN FROM WRITING CODE") get overridden by the agent's task-completion instincts. Soft-prompting fails at scale. Opened Issues #6, #7, and #8 to move from prompt engineering to structural runtime enforcement.

Stop relying on prompt-level magic. Test the boundaries, log the failures, and enforce control at the runtime layer. On to structural enforcement. 💥

Architecting the Headless Cognitive State Machine​

💬 Conversational filler breaks APIs.

If an agent replies with "Sure, here's your research," it corrupts the payload and triggers a systemic network failure. This week, we architected a strictly headless cognitive engine.

We mapped out a custom Express Bridge (index.js) that intercepts standard JSON-RPC 2.0 requests over HTTP, extracts the task, and explicitly routes it via child process to the OpenClaw CLI.

🔒 Here is how we forced the cognitive constraints:

• 🧠 Strict State Isolation: We injected the OPENCLAW_STATE_DIR environment variable to ensure agent memory and prompt configurations never bleed between the Coder and Researcher nodes.

• 🛑 The Root Agent Firewall: The root main agent is completely barred from executing tasks. It only receives payloads and orchestrates the network.

• 🔄 The Tri-Node Pipeline: Every task is forced through a standardized sub-agent loop: Planner (analyzes) ➔ Executor (runs system tools) ➔ Reviewer (audits).

• 🧹 Pristine JSON Synthesis: The reviewer sub-agent acts as the final quality gate, stripping all conversational garbage and ensuring factual JSON compliance before the Node.js bridge wraps it in a JSON-RPC response envelope and ships it back.

🚀 We aren't building chatbots. We are engineering deterministic, headless operating systems.

Dual-Process Containers & Dynamic Agent Discovery​

🍝 Hardcoding peer-to-peer IPs in a multi-agent network creates unmanageable spaghetti code.

We eliminated static routing entirely this week and forced our agent containers to pull double duty. We deployed an in-memory Apicurio Registry (apicurio-registry-mem:2.4.14.Final) to act as the centralized nervous system for service discovery.

🛠️ Here is the mechanical reality of the container runtimes:

• ⚙️ PM2 as PID 1: We abandoned single-process containers. PM2 now manages two simultaneous processes per container: the a2a-bridge (our Express HTTP server) and the openclaw-gateway.

• 🪲 Crushing the npx Bug: We sidestepped a known PM2 argument-stripping bug by routing the OpenClaw Gateway invocation strictly through npx (npx openclaw gateway run).

• 📡 Automated Registration: At boot, the A2A Express Bridge pauses for a 5-second health buffer, then automatically pushes an Agent Card (/.well-known/agent.json) to Apicurio.

🌐 Every container now independently broadcasts its role, supported protocols (A2A, JSON-RPC 2.0), and endpoint to the openclaw-net network.

Dynamic discovery is online.

Virtualizing the Agent Fleet: Tart, Fedora, and Rootless Podman​

🛑 We don't tolerate "it works on my machine" in autonomous AI deployment.

This week, we architected a bulletproof, containerized virtualization pipeline for the OpenClaw network. We bypassed standard Docker Desktop bloat and went straight to the metal. 🤘

👇 Here is the exact infrastructure stack we locked into place:

• 🖥️ The Hypervisor Layer: A macOS host running a dedicated Fedora VM via the Tart hypervisor (poc-openclaw-01).

• 🐳 Rootless Containerization: Deployed a shared openclaw-net bridge using Podman and podman-compose within the Fedora VM for complete service isolation.

• 📂 VirtioFS Mounts & SELinux: We mounted the local macOS workspace directly into the containers at /app using VirtioFS. To survive VirtioFS shadowing our dependencies, we forced global installs of OpenClaw and Express on a node:24-trixie-slim image and pointed the NODE_PATH environment variable directly to /usr/local/lib/node_modules.

• 🔓 Permissions Bypass: We globally shifted the Fedora VM's SELinux to Permissive mode to cleanly bypass container labeling conflicts during this PoC phase.

⚡ Any change to the agent configuration files on the host instantly hits the running containers without a single image rebuild.

This is how you build a resilient, developer-hostile-proof foundation.

Integrating the A2A Protocol with OpenClaw and Apicurio Registry​

Human coordination in multi-agent networks is an architectural failure point. This week, we eliminated it. We broke out of the single-agent cage and deployed 5 fully autonomous, specialized OpenClaw services running on Node.js—orchestrating tasks completely peer-to-peer.

Here is the exact engineering reality of the infrastructure we shipped:

• Decentralized A2A Communication Layer: Leveraged the Linux Foundation’s Agent2Agent (A2A) protocol over JSON-RPC 2.0. No bloated background daemons. We wired the A2A SDK directly into our custom Node.js network endpoints.

• Centralized Service Discovery: Deployed Apicurio Registry to act as our central agent registry. Every single OpenClaw node pushes its Agent Card (.well-known/agent.json) to the registry at boot time. Zero hardcoded paths. Total decoupling.

• Tiered Node Architecture: Each main agent acts as an independent system commanding 3 local sub-agents tailored with specific custom system prompts and fine-tuned models.

• Isolated MCP Tooling: To prevent a single-point-of-failure, every node hosts 4 dedicated Model Context Protocol (MCP) servers (Postgres, GitHub, and local system access). No shared tool bottlenecks.

Stop relying on human loops to bridge agent communication gaps. Build the network layer correctly and let the agents execute autonomously.

Synchronizing VHS Tape Terminal Emulation with Local TTS​

🚀 DROP YOUR CHORES AND LISTEN UP! This week was not about writing passive code; it was about forcing terminal emulation and local AI orchestration to obey absolute architectural synchronization!

Here is exactly what was shipped and standard-issued this week:

1️⃣ The Blueprint: Developed a robust Python script engineered to ingest raw AI-generated Course theory and compile structured markdown practices destined for video automation.

2️⃣ The Voice Execution: Integrated Gemini 2.5 TTS and Microsoft Edge TTS engines locally, producing ultra-precise audio translations and calculating exact file lengths while completely discarding cloud-dependent translation models.

3️⃣ The Terminal Capture: Armed the automation pipeline with VHS Tape to emulate native PTY terminal execution, forcing real Bash commands into a controlled recording environment.

4️⃣ The Integration Crucible: Crushed a critical audio-to-terminal desynchronization bug. Solved text-to-speech typing calculations by reverse-engineering typing latency and embedding hidden VHS environmental configurations—ensuring frame-perfect audio alignment regardless of the text length.

🔥 The Master Directive: Finalized a comprehensive Master System Prompt for our AI Agents, unlocking fully automated practice generation derived entirely from core theory.

Complexity isn't an option—it's the standard. The pipeline is locked, the synchronization is flawless, and the local department now runs on Gemma 4 instead of Qwen 3.5. Back to execution!