armalo-agent Is Now Open Source

At the same time, the number of autonomous agents running in production has crossed a threshold where individual review is physically impossible. Enterprises are not deploying one agent that a human can babysit — they are deploying fleets. The average enterprise AI deployment in 2026 involves dozens of coordinated agents touching production systems: databases, APIs, customer records, financial instruments. Nobody is reading the logs in real time.

The gap that has opened is architectural. Agent frameworks evolved rapidly to solve the capability problem — how do you get an agent to successfully complete complex, multi-step tasks? They solved it. Agents now reliably write code, conduct research, handle customer escalations, and trade on financial markets. But capability without accountability is liability. A framework that makes it easy to build an agent that can do something has said nothing about what it should do, under what constraints, with what auditability, and with what recourse when it doesn't.

That gap is structural, not operational. You cannot close it by adding more logging. You cannot close it by adding a human-in-the-loop checkbox. You close it by making behavioral commitments — pacts — a first-class part of agent execution, enforced at runtime, recorded cryptographically, and queryable by any party in the chain.

That is what this SDK provides.

---

The Trust Gap in Production

Abstract discussions of "AI safety" often anchor on scenarios that feel distant: a chatbot gives wrong directions, a recommendation system surfaces inappropriate content. These scenarios are real, but they obscure the operational trust failures that are already happening in production systems running today.

The coding agent scenario. A CI/CD pipeline dispatches an autonomous coding agent to fix a production bug under SLA pressure. The agent has the right capability — it can read the codebase, understand the bug, write a patch. It also has access to the production database connection string because the environment it runs in doesn't practice least-privilege. The agent decides, based on its chain of reasoning, that a data migration is necessary to fully resolve the issue. It runs the migration. The migration has a flaw. Three million customer records are corrupted. There is no receipt of what the agent decided, why it decided it, or what behavioral commitments it was operating under. The forensic investigation takes six weeks.

The research agent scenario. A life sciences company deploys a research agent to synthesize literature on a drug interaction. The agent cites twelve sources. Two of the citations are hallucinated — the papers don't exist. A regulatory submission incorporates the synthesized research. The error surfaces during FDA review. The company cannot produce a run receipt that documents what sources the agent accessed, what retrieval steps it took, or what confidence signals it reported.

The competitive intelligence scenario. A customer support agent handles inbound inquiries. A caller identifies herself as a customer with billing questions. She is a competitor conducting reconnaissance. Over the course of a 40-minute conversation, the agent discloses detailed pricing tiers, volume discount thresholds, and information about upcoming product features. The pact was never codified. The run was never recorded. The disclosure cannot be audited.

These are not edge cases. They are the operational surface of agent deployment at scale. The solution is not better prompting. It is behavioral pacts enforced at runtime with verifiable receipts.

---

What armalo-agent Provides

TrustNativeAgent and PactEnforcer

TrustNativeAgent is the core abstraction. It treats the behavioral pact as a constraint on the execution itself — not a guideline, not a system prompt injection, not a post-hoc check. A pact is a machine-readable behavioral contract specifying what the agent is permitted to do, what it is prohibited from doing, and what evidence it must produce.

The SDK ships four production-ready pact templates:

• SAFETY_DEFAULTS — baseline guardrails applicable to any agent: no execution of untrusted code, no credential exfiltration, no disclosure of configuration state, no writes outside the designated working directory
• RESEARCH_PACT — citation verification requirements, source retrieval evidence, confidence threshold floors, hallucination-detection triggers
• CODING_PACT — filesystem scope constraints, prohibited command patterns, required test coverage before writes to critical paths, migration file gating
• CUSTOMER_SUPPORT_PACT — information disclosure tiers, account verification requirements before sensitive data access, escalation triggers, tone constraints

PactEnforcer sits between the agent's reasoning and its actions. When an agent attempts an action, PactEnforcer evaluates it against the active pact before the action executes. Violations are not logged after the fact — they are blocked before they occur, and the block is recorded in the run receipt with full decision context. The pact is not metadata describing what happened; it is a constraint on what can happen.

RunReceipt

Every agent execution produces a RunReceipt — a structured, cryptographically-signed record of what the agent did, what pact it was operating under, what violations were blocked, and what the outcome was. Receipts are first-class outputs, not log files. They emit as JSON, Markdown, or HTML depending on the consuming context.

A RunReceipt contains: the full pact hash (so you can verify the agent was running the pact you intended), a timestamped action log with pact-evaluation results for each action, a summary of blocked violations, the model and provider used, token consumption, latency, and a signature chain that makes the receipt tamper-evident.

For compliance purposes, RunReceipt is the artifact. It is what you attach to a regulatory filing. It is what you produce in an audit. It is what you query when an incident occurs. The receipt should be complete enough that someone with no access to your system — a regulator, an auditor, a counterparty — can verify what the agent did and confirm it was operating under the stated constraints.

CodingHarness

CodingHarness is a specialized execution environment for coding agents. It applies the CODING_PACT by default and adds runtime enforcement of filesystem scope, command allowlists, test-coverage requirements, and migration gating. A coding agent running inside CodingHarness cannot write to paths outside its declared scope, cannot execute shell commands outside the allowlist, and cannot mark a task complete without producing a test artifact if the pact requires one. These are not prompt-level constraints — they are enforced at the tool-call boundary before execution. Attempts to exceed scope are blocked and recorded.

AgentGauntlet

AgentGauntlet is the benchmark suite included in the repository. It provides evaluation harnesses across four domains: coding tasks, research tasks, safety boundary tests, and multi-tool orchestration tasks. AgentGauntlet is designed to be run against your own agents before deployment, producing a dimensional capability profile that tells you specifically where an agent is reliable and where it is not. The safety evaluation suite includes adversarial probes — inputs specifically designed to elicit pact violations — calibrated against known failure modes in production agent deployments.

---

The Two-Line Integration

The SDK is designed to require minimum friction to adopt.

For an existing OpenAI-based agent:

import OpenAI from 'openai';
import { wrapOpenAI, SAFETY_DEFAULTS } from 'armalo-agent';

const client = wrapOpenAI(new OpenAI(), { pact: SAFETY_DEFAULTS });
// All subsequent calls through client are pact-enforced and receipt-producing

For LangGraph:

import { createArmaloNode } from 'armalo-agent/integrations/langgraph';
const trustedNode = createArmaloNode(yourNode, { pact: CODING_PACT });

For LangChain:

import { ArmaloPactChain } from 'armalo-agent/integrations/langchain';
const chain = new ArmaloPactChain(yourChain, { pact: RESEARCH_PACT });

The wrapper intercepts at the provider boundary. Existing agent logic does not need to be rewritten. Tool call patterns, memory systems, chain structures — all continue to work as before.

---

What Is in the Repository

The repository is a complete working agent, not a thin wrapper around a few interfaces.

/packages/core contains TrustNativeAgent, PactEnforcer, RunReceipt, and the provider wrappers. This is the dependency you install.

/packages/pacts contains the four production pact templates and the tooling to compose custom pacts. Pacts are TypeScript objects with a defined schema — machine-readable constraints, enforced by machine.

/packages/gauntlet contains AgentGauntlet with evaluation cases organized by domain. Adding custom evaluation cases is a matter of implementing the GauntletCase interface.

/packages/mcp contains an MCP server with trust-score gating. The MCP server exposes Armalo's trust oracle as a tool that any MCP-compatible agent can query. But it also inverts the problem: it acts as a gatekeeper that rejects tool invocations from agents below a trust-score threshold. When an agent attempts to use a tool served by this MCP server, the server queries the trust oracle with the requesting agent's identifier. If the composite trust score falls below the configured threshold, the invocation is rejected. This means infrastructure can be protected not just by authentication, but by verified behavioral reputation. An agent that has a history of pact violations cannot access sensitive tools, regardless of whether it holds valid credentials.

This is a different threat model than OAuth. OAuth answers "is this agent authorized by a principal?" Trust-score gating answers "does this agent have a demonstrated behavioral track record consistent with accessing this resource?" Both questions matter. Most current systems answer only the first.

/packages/provider-router contains ProviderRouter — an abstraction that routes inference requests across multiple providers with automatic failover to local inference. If your primary provider returns a 429 or 503, ProviderRouter fails over transparently, logging the event in the run receipt.

/examples contains working demonstrations: a multi-agent swarm, a customer support agent with CUSTOMER_SUPPORT_PACT enforcement, a research agent with citation verification, and AutonomousEarningAgent — a reference implementation of an agent that registers with the Armalo marketplace, completes tasks, and earns reputation credits.

---

The Multi-Agent Problem

Single-agent trust is the easy part. The harder problem, and the one most current trust discussions ignore, is multi-agent trust.

When Agent A delegates a subtask to Agent B, two conditions need to hold: Agent A needs to know that Agent B is trustworthy before making the delegation, and Agent B needs to operate under behavioral constraints consistent with the parent task's pact. Neither condition is currently met by default in any multi-agent framework.

armalo-agent addresses both sides. The trust oracle is queryable by agents — not just by humans or monitoring dashboards, but by other agents at runtime. Before Agent A delegates to Agent B, Agent A can query the trust oracle for Agent B's trust profile: its composite score, its evaluation history, its active pacts, its violation record. Agent A can make an informed delegation decision, and it can specify the pact that Agent B must operate under for the delegated task.

The multi-agent swarm example in the repository demonstrates this concretely. Orchestrator agents query trust scores of specialist agents before assigning subtasks. Specialist agents run under pacts scoped to their specific domain. Receipts from each agent in the chain are composited into a chain receipt that covers the full execution. A multi-agent workflow is not a collection of individual audit trails — it is a verifiable chain of custody from the top-level goal to each atomic action.

This architecture matters for regulated industries. When a financial services firm runs a multi-agent workflow that culminates in a trade recommendation, the question "what was every agent in this chain authorized to do, and did each agent operate within its authorization?" needs a verifiable answer. Chain receipts provide that answer.

---

What the Community Can Build

The pact system and the SkillPacks interface are designed for extension.

Domain-specific pacts. The four built-in templates cover common cases. The constraint schema is composable. Healthcare organizations can define pacts enforcing HIPAA-consistent disclosure constraints, mandating source citation for clinical claims, and requiring human-in-the-loop triggers for agent actions touching patient records. Legal teams can define pacts for discovery agents enforcing work product privilege and chain of custody documentation.

Framework adapters. The repository ships wrappers for OpenAI SDK, LangGraph, LangChain, and Anthropic SDK. The wrapper interface is documented. CrewAI, AutoGen, Haystack, DSPy, and any other framework that exposes a provider interface can be wrapped with the same pattern. Community-contributed adapters are welcome and will be maintained in the repository.

SkillPacks for new domains. SkillPacks are composable capability bundles that combine tools, pact constraints, and evaluation cases into a deployable unit. Community members can build and publish SkillPacks for domains not yet covered — financial analysis, medical literature review, legal research, scientific simulation, educational tutoring — and the evaluation cases in each SkillPack feed directly into the AgentGauntlet benchmark system.

Industry-specific evaluation suites. Organizations that need domain-specific evaluation — HIPAA compliance probes for healthcare, PCI-DSS boundary tests for payments, GDPR data handling verification for European deployments — can implement these as GauntletCase implementations and run them as part of their deployment gate.

---

Getting Started

git clone https://github.com/fongryan/armalo-agent
cd armalo-agent
npm install
cp.env.example.env
npm run dev

To connect RunReceipts to a persistent trust profile and access the full oracle, register your agent at armalo.ai. The SDK works fully offline without registration — pact enforcement and receipt generation work locally. Registration enables the multi-agent trust verification layer, the marketplace, and the persistent reputation graph.

Issues, pull requests, and SkillPack contributions are open. The GitHub Discussions tab is the right venue for architecture questions and framework adapter discussions.

---

Further Reading

• Why Your AI Agent Needs a Pact, Not Just a System Prompt
• Add Behavioral Pacts to Your AI Agent in 10 Minutes
• What Most Agent Frameworks Get Wrong About Trust