DEV Community: tercel

Give Your Coding Agent a Governed CLI Workflow with apexe

tercel — Fri, 16 Oct 2026 12:14:58 +0000

An agent task starts simply: list a directory, read a file, inspect a tool. As the task grows, those small calls become a workflow with real permissions and side effects.

That is a useful place to introduce apexe: a governed execution layer for CLI tools and HTTP APIs. It gives existing commands typed contracts and applies configured policy before execution, with records of executions and refusals.

Here is how to start with a local CLI workflow, then connect it to the agent or protocol client you use.

1. Prepare apexe and a trusted CLI

Use a prebuilt binary, or build from source with stable Rust and Cargo:

git clone https://github.com/aiperceivable/apexe.git
cd apexe
cargo install --path .
apexe --version

The workflow below targets Unix CLI tools. macOS and Linux are the main starting points; native Windows CLI discovery is not supported. Git is needed to acquire the rules corpus, and the CLI binaries you want to use must already be installed.

Initialize coverage and inspect the result:

apexe init
apexe list --verbose

init obtains the configured rules source, normally cli-permissions, checks matching installed commands and variants, and writes bindings plus a starter ACL.

Review ~/.apexe/acl.yaml. A new policy defaults to deny, with generated allow rules for local readonly operations. Existing manual rules and policy defaults are preserved. Treat generated classifications as material to review.

Read the init report, including skipped tools, warnings, and native_ready module IDs. This is where you learn which entry points your installation can actually use.

2. Preview one native invocation

Native execution accepts familiar argv:

apexe exec --dry-run -- ls -la

For this example, you need a matching reviewed native binding. The current native pilot covers BSD cat, head, and ls. A Linux installation may successfully scan GNU tools while lacking native grammar for this call; scanning coverage and native eligibility are separate.

Inspect the preflight's validity, execution mode, module, ACL decision, approval requirement, and argument/path checks. Confirm that it describes the operation and policy you intended.

Only after reading an admitted preflight, submit a separate execution call:

apexe exec -- ls -la

Native stdout and stderr pass through, and apexe preserves the child's exit status. You do not need to activate a shell environment or run an MCP server.

Keep preview and execution separate in an agent workflow: the point is to inspect the result before starting the child. Execution checks the request again; a preview does not reserve permission or grant human approval.

3. Use module JSON when the binding has no native grammar

Module JSON is another local interface. Start by inspecting the installed schema:

apexe list --verbose --format json

The output's modules array contains each module's id and input_schema. Use the property names and shapes from your own binding.

For example, if your cli.ls schema advertises a file array, preview:

apexe exec cli.ls --input '{"file":["."]}' --dry-run

After inspecting an admitted result, execute separately:

apexe exec cli.ls --input '{"file":["."]}'

Module mode captures the result as JSON, including stdout, stderr, and exit_code; it supplies null child stdin. Native mode preserves streams, with stdin inheritance only where reviewed capabilities permit it.

Both routes apply their normal governance checks. A missing native grammar can justify selecting module JSON for the same operation. An ACL or path refusal calls for resolving the denied request with the operator.

4. Give your terminal agent the same workflow

apexe includes one shared routing Skill for Claude Code, Codex, pi, and OpenCode. From the source checkout:

python3 scripts/install_agent_skill.py --project-dir /path/to/your-project

Replace that destination with the project where the agent works. Follow the Agent Skill guide to declare the execution route and selected policy in the host's project instructions.

The Skill guides the agent to resolve configuration before its first task command, route external CLI calls through explicit exec, preview new or changed calls, and stop on governance refusals. Explicit exec works without shims or MCP.

For a pipeline, the shell still owns the pipe. Each external stage needs its own governed invocation, and the Skill calls for preflighting stages sequentially before execution. Shell redirection happens outside apexe's typed-path checks.

Installing the Skill alone does not enroll every project or intercept an unrestricted terminal. Compulsory routing requires host enforcement.

5. Add an interface when you need it

For existing shell workflows, optional env integration installs eligible external-command shims:

apexe env --enable
source ~/.apexe/bin/apexe-activate.sh
apexe env --check

Use this after bindings and policy are ready. Shims preserve familiar command names for covered tools. Builtins, aliases, absolute paths, and uncovered commands remain outside that route.

For an MCP client:

apexe serve --acl ~/.apexe/acl.yaml

For A2A:

apexe a2a --acl ~/.apexe/acl.yaml

Servers need the explicit ACL flag for access control. Local exec uses caller local and loads the default ACL when present; if none is loaded, access control is inactive. MCP interactive approval is opt-in with --enable-approval and a compatible client. Local execution has no interactive approval client, so calls that actually need that decision fail closed. A2A has no interactive approval transport; approval-store support requires library integration.

Have an HTTP API too? serve and a2a can import supported operations from OpenAPI 3.0/3.1 documents alongside CLI modules. See the OpenAPI guide for the supported JSON proxy surface and credential setup. HTTP import is a server feature.

Keep the contract current

After a CLI changes, check its source contract:

apexe verify --report ./drift-report.json

Optional explicit behavioral cases add evidence for the invocations tested. Recorded evidence is bound to binding, executable, and case digests, so changes can invalidate it. It does not certify every possible use of a CLI.

Know the execution boundary

Governed CLI calls use structured inputs, configured ACLs, schema-typed path checks, environment scrubbing, timeouts, and auditing. apexe passes argv to the subprocess without evaluating a shell command string.

An allowed process still has the host process's privileges. apexe is not an OS sandbox. Pair it with the account and isolation boundary your workload needs, and read the threat model.

The project is Rust-based and Apache-2.0 licensed. Start with one trusted CLI and one operation you can inspect from preflight through audit.

Explore apexe on GitHub · Read the quick start

Which CLI would you like your agent to use through a reviewed execution contract?

Distributed Orchestration vs Agent Reasoning

tercel — Thu, 15 Oct 2026 02:47:51 +0000

A lot of “AI agent orchestration” diagrams quietly merge two very different responsibilities:

deciding what to do next (reasoning)
actually running distributed work reliably (orchestration)

If you’ve ever operated a workflow engine, you know the second problem doesn’t go away just because a model is choosing the steps.

Agents are planners, not workflow engines

Agent frameworks are great at:

breaking down fuzzy tasks
picking tools / capabilities
adapting a plan based on intermediate outputs

They’re not good at:

guaranteeing retries and idempotency
managing long‑running state
coordinating fan‑out and aggregation at scale

Those are classic workflow concerns.

What orchestration is responsible for

A real orchestration layer needs to:

persist workflow state
handle node restarts and deploys without losing work
retry failed steps with backoff
apply idempotency / deduplication
support compensation / rollbacks for multi‑step flows

In an agentic system, that orchestration is often built on top of a governed capability runtime.

Why pair a runtime with orchestration?

A protocol‑neutral capability runtime gives you:

schema‑validated inputs/outputs for each operation
identity / ACL / approval checks
structured traces and events per invocation

An orchestrator then uses those capabilities as building blocks, chaining them together under strong guarantees.

The agent stays in the role of planner:

it proposes which capabilities to call and with which parameters
it can react to structured errors and adjust the plan
it doesn’t try to be the persistence or retry layer

This separation has practical benefits:

Debuggability
When a flow fails, you can see where: in planning, in runtime validation, or in orchestrated execution.
Safety
Every step is subject to the same ACLs, approvals, and audit behavior, regardless of whether it was triggered by an agent or a human.
Evolution
You can swap agent frameworks or tool protocols without rewriting the orchestration and governance layers.

A small, realistic first step

If you’re starting from an agent demo that calls services directly, you don’t have to refactor everything at once.

Try this:

pick a single, non‑trivial flow (e.g., canary deploy, batch data fix)
expose the underlying operations as governed capabilities with schemas
route all calls through a runtime that adds identity, ACLs, approvals, and traces
have a simple orchestrator (queue + worker, or a workflow engine you already use) own retries and long‑running state

Once that path works, expand the set of capabilities and flows that use it.

The key shift is mental: treat agents as planners on top of a governed, orchestrated system – not as replacements for the parts of your stack that already give you reliability guarantees.

Distributed Orchestration vs Agent Reasoning

tercel — Wed, 14 Oct 2026 02:38:17 +0000

A lot of “AI agent orchestration” diagrams quietly merge two very different responsibilities:

deciding what to do next (reasoning)
actually running distributed work reliably (orchestration)

If you’ve ever operated a workflow engine, you know the second problem doesn’t go away just because a model is choosing the steps.

Agents are planners, not workflow engines

Agent frameworks are great at:

breaking down fuzzy tasks
picking tools / capabilities
adapting a plan based on intermediate outputs

They’re not good at:

guaranteeing retries and idempotency
managing long‑running state
coordinating fan‑out and aggregation at scale

Those are classic workflow concerns.

What orchestration is responsible for

A real orchestration layer needs to:

persist workflow state
handle node restarts and deploys without losing work
retry failed steps with backoff
apply idempotency / deduplication
support compensation / rollbacks for multi‑step flows

In an agentic system, that orchestration is often built on top of a governed capability runtime.

Why pair a runtime with orchestration?

A protocol‑neutral capability runtime gives you:

schema‑validated inputs/outputs for each operation
identity / ACL / approval checks
structured traces and events per invocation

An orchestrator then uses those capabilities as building blocks, chaining them together under strong guarantees.

The agent stays in the role of planner:

it proposes which capabilities to call and with which parameters
it can react to structured errors and adjust the plan
it doesn’t try to be the persistence or retry layer

This separation has practical benefits:

Debuggability
When a flow fails, you can see where: in planning, in runtime validation, or in orchestrated execution.
Safety
Every step is subject to the same ACLs, approvals, and audit behavior, regardless of whether it was triggered by an agent or a human.
Evolution
You can swap agent frameworks or tool protocols without rewriting the orchestration and governance layers.

A small, realistic first step

If you’re starting from an agent demo that calls services directly, you don’t have to refactor everything at once.

Try this:

pick a single, non‑trivial flow (e.g., canary deploy, batch data fix)
expose the underlying operations as governed capabilities with schemas
route all calls through a runtime that adds identity, ACLs, approvals, and traces
have a simple orchestrator (queue + worker, or a workflow engine you already use) own retries and long‑running state

Once that path works, expand the set of capabilities and flows that use it.

The key shift is mental: treat agents as planners on top of a governed, orchestrated system – not as replacements for the parts of your stack that already give you reliability guarantees.

Practical Patterns for AI Agent Governance in Production

tercel — Wed, 07 Oct 2026 00:53:29 +0000

When an AI agent starts calling real systems – deploy pipelines, billing, CRM, data workflows – “governance” stops being optional.

Over the last year, a few practical patterns have emerged for teams that got agents into production without terrifying security and infra.

Pattern 1: Treat capabilities as a catalog, not just functions

Instead of wiring agents to ad‑hoc endpoints, define a capability catalog:

stable capability IDs
machine‑readable schemas for inputs and outputs
metadata (owner, risk, environments)

The same capabilities are callable by humans (CLI), services (HTTP/RPC), and agents. That shared catalog becomes your map of what the organization can actually do.

Pattern 2: Build a centralized enforcement pipeline

Sprinkling ACL checks and approvals across N services doesn’t scale.

Introduce a runtime layer that every capability invocation passes through. It should:

resolve identity and caller context
enforce ACLs
evaluate approval conditions
run middleware for logging / metrics / policies

Downstream services implement business logic; the runtime decides whether the call is allowed and how it should be wrapped.

Pattern 3: Keep protocols as adapters on the edge

MCP, HTTP, CLIs, internal RPC – all are just ways to reach the same capabilities.

If each protocol carries its own governance semantics, you’ll get drift. Instead, let each protocol adapter:

map protocol requests into capability calls
inject identity and context
route through the same enforcement pipeline

That way, adopting a new tool protocol is mostly an adapter exercise, not a rewrite of core rules.

Pattern 4: Evidence as a first‑class output

When something breaks, teams want more than logs. They want evidence.

Your runtime can emit:

structured “invocation” events (who, what, where)
consistent error shapes with trace IDs
hooks for usage / cost tracking

Because this happens in one place, you don’t depend on every service getting logging exactly right.

Pattern 5: Offload determinism to an orchestrator

Agents are planners; they’re not great at guaranteeing that a fan‑out of 1,000 jobs completes exactly once.

Pair agents with a workflow engine that handles determinism:

retries and idempotency
timeouts and cancellation
compensation logic

The agent assembles a plan in terms of governed capabilities; the orchestrator executes that plan reliably.

Pattern 6: Iterate on one end‑to‑end path

A realistic path for many teams:

pick a non‑trivial, high‑value capability (e.g., canary deploy)
give it a schema, policies, and full tracing
expose it to a human interface and an agent
run it in production with tight monitoring

Use the friction you hit there to refine your runtime, then scale out to more capabilities.

These patterns don’t depend on a specific framework. They do depend on drawing a clear line between:

capabilities (what can be done)
the governed runtime (who can do it, under what rules)
protocols and agents (how it’s requested)

Once that separation exists, agent governance becomes a matter of evolving policy and runtime behavior – not rewriting every integration when a new agent pattern appears.

Why Raw Shell Access Is the Wrong Agent Integration—and What apexe Does Instead

tercel — Thu, 01 Oct 2026 13:21:06 +0000

Your organisation probably already owns the capabilities its agents need. They live in git, kubectl, jq, curl, operational scripts, and internal Unix command-line tools.

The usual choice is uncomfortable: give an agent shell access, or rebuild every useful command as an API or MCP server.

apexe is built for the middle path. It scans an existing CLI, turns each command into a schema-driven apcore module, and serves those modules through MCP or A2A with execution-time controls.

existing CLI → module contract + reviewed policy → governed Executor → many agent clients
What is supported today?
Precision matters in agent infrastructure. The current product boundary is:

Item apexe 0.8 status
Unix CLI tools on PATH Supported by apexe scan
macOS/Linux system utilities (ls, cat, cp, sort, …) Supported as CLI tools, including BSD-aware parsing
Built-in parsers (Man, BSD Usage, GNU, Click, Cobra, Clap) Supported scanner feature
ACL for scanned CLI modules Supported when supplied with --acl
MCP Supported by apexe serve (stdio, HTTP, Explorer)
A2A Supported by apexe a2a
OpenAPI input Not supported by the apexe CLI today
OpenAPI deserves a direct note. The apcore toolkit has OpenAPI-related functionality, but apexe does not call its OpenAPIScanner. apexe is currently a CLI-to-agent bridge, so we should not market OpenAPI support as shipped functionality.

Start with a real CLI
apexe scan git curl jq
apexe list
apexe serve --show-config claude-desktop --acl ~/.apexe/acl.yaml
The scan is deterministic: help text, man pages, and shell completions—not an LLM. It creates one binding per command, such as cli.git.log or cli.curl, and each binding contains JSON Schema for flags and operands.

An agent calls a JSON object rather than composing a command string:

{
"url": "https://httpbin.org/get",
"silent": true
}
apexe validates this object, builds argv, and launches the program directly. No shell parses the resulting arguments.

One capability configuration, many agent clients
The goal is not to create a separate tool definition and security policy for every agent product. Bindings and ACL are the source of truth:

~/.apexe/bindings/ + ~/.apexe/acl.yaml → apexe → Claude / Codex / Pi / another MCP client
This does not mean every client shares one configuration-file format. Each host still needs its own MCP connection entry. What stays shared is the command or HTTP endpoint, the scanned module bindings, and the reviewed ACL.

apexe can generate connection snippets for Claude Desktop and Cursor:

apexe serve --show-config claude-desktop --acl ~/.apexe/acl.yaml
apexe serve --show-config cursor --acl ~/.apexe/acl.yaml
Codex can register the same local stdio server:

codex mcp add apexe -- apexe serve --acl ~/.apexe/acl.yaml
Pi and other MCP-capable clients can connect through their own MCP configuration mechanism. apexe does not currently generate a Pi-specific file, so the client must support the transport you select. For a shared deployment, run one authenticated HTTP server and have compatible clients connect to that endpoint.

Why the module contract matters
The contract is what lets the same capability retain its meaning across delivery surfaces:

apexe serve exposes it over MCP, using stdio by default or HTTP with a browser Explorer.
apexe a2a exposes the same governed modules as agent skills.
--prefix and --tags reduce the registered surface before a client can discover or invoke it.
Policy does not need to be rewritten per protocol because MCP and A2A share the same Executor.

Governance is a product feature, not a checkbox
apexe scan writes a default-deny ACL. It is a starter policy, not an invisible decision: enforcement begins only when an operator serves with --acl.

apexe serve --acl ~/.apexe/acl.yaml
The ACL controls which capability may be called. An always-on path guard answers a different question: what filesystem location may this specific call touch? It checks path-typed inputs after resolving symlinks and traversal, protects system paths from writes, and protects credential locations from both reads and writes.

apexe policy
apexe policy --path /etc/nginx/conf.d --mode write
Every child process is shell-free, runs with a scrubbed environment, has a timeout and output cap, and can produce a private audit record. These are meaningful safeguards, but they are not a sandbox. Run exposed tools inside the container, VM, account, and network boundary your risk model requires.

Why 0.7 and 0.8 matter
The current releases make the boundary more useful in practice: path protection, argument-sensitive approvals, refusal of verified command-executing parameters, binary availability checks, an explicit default-deny tier for network-reaching tools, and externally maintained verified CLI overlays.

Bindings now live by default under ~/.apexe/bindings and record which apexe version produced them. Existing users should rescan after upgrading:

apexe scan git curl jq --no-cache
apexe list --available-only
What comes next: local execution, then native terminal workflows
The next proposed feature is F8 local execution. It is deliberately split into two stages rather than treating a shell wrapper as a shortcut.

Stage 1, apexe run, is a structured local entry point for one scanned module at a time:

apexe run cli.ls --input '{"long": true, "paths": ["/tmp"]}' --acl ~/.apexe/acl.yaml
It will reuse the same Executor that MCP and A2A use, produce captured output, and make preflight decisions inspectable from the terminal. It is not native shell syntax and does not provide streaming stdin or pipelines.

Stage 2, apexe env with PATH shims, is the intended end-user terminal experience. Eligible external commands retain their normal names and argv syntax, so an existing pipeline such as ls -l /tmp | grep ERROR | head -20 can remain unchanged. Each stage is independently resolved to a scanned module and receives schema validation, verified cli-permissions facts, ACL, path guard, timeout, output limit, and audit logging—without using sh -c.

This is not available yet. Its safety depends on contracts that are still being settled: passthrough I/O, an explicit human-reviewed allowlist for modules that may read streaming stdin, PATH isolation, and measurements of refusal rate and shim latency. It also cannot intercept shell builtins, aliases/functions, or absolute-path calls. Read the F8 design for the exact boundary.

Join the design conversation
The interesting question is not “can an agent run a command?” It can. The question is which existing capability sources should share a contract, governance layer, and protocol delivery model.

We would love your comments:

Which CLI or internal tool would you expose first?
Which agent hosts—Claude, Codex, Pi, or another MCP client—need the same governed tool surface?
Which existing scripts or pipelines should a governed PATH-shim mode support first?
Would OpenAPI ingestion be valuable in the same workflow?
What must an operator review before an agent can use a newly discovered capability?
Project: aiperceivable/apexe

Designing Schema-First Capabilities for AI Agents

tercel — Thu, 01 Oct 2026 05:49:02 +0000

If your AI agent can call production systems, the contract between the agent and your capabilities is more important than the prompt.

A schema‑first capability design puts that contract at the center of your architecture and lets everything else – CLIs, HTTP APIs, agent tools – project from it.

What is a schema‑first capability?

Take a real operation in your system:

create_invoice
deploy_service
reset_user_password

Instead of documenting this informally and wiring it directly into APIs, you define a machine‑readable schema that captures:

input fields, types, and constraints
output structure
error variants and their shapes

This schema is authoritative across all callers: humans, microservices, and AI agents.

Why do this for agents?

LLMs are not type‑safe. They will:

omit required fields
invent new ones
send wrong types ("five" instead of 5)

If you validate deep inside your application, you only discover problems after partial side effects. A schema‑aware runtime can:

validate inputs before execution
validate outputs before returning
produce structured errors the agent can learn to handle

That alone dramatically reduces “mystery failures” in production.

Schema as a governance anchor

Once every capability has a stable ID and schema, you can attach policy:

which identities / roles may call it
which calls need approval
which environments it applies to
what logging, tracing, and usage hooks must run

Crucially, this policy is attached to the capability itself, not to any single protocol.

Multi‑language, one contract

Most organizations run Python, TypeScript, and at least one systems language. A normative schema lets you:

generate / validate language‑specific SDKs
write conformance tests once
keep contracts synchronized across stacks

Agents don’t care which language implements a capability; they care that the contract is consistent.

A concrete pattern to start

Choose an existing, non‑trivial operation.
Write its real input/output contract and error cases.
Encode that as a schema.
Wrap the implementation in a small runtime layer that validates against the schema and emits structured events.
Expose it through one additional surface (CLI, HTTP, or a tool protocol).

Measure:

how often validation catches bad calls
how much easier debugging becomes with structured traces
how straightforward it is to add another surface once the capability exists

Over time, your catalog of schema‑first capabilities becomes the safe surface area your agents can operate in, with the same rules and evidence as the rest of your stack.

What a Governed Agent Runtime Actually Does

tercel — Tue, 29 Sep 2026 01:33:25 +0000

Most AI agent prototypes fail not because the model is weak, but because the path from the model to real capabilities is essentially ungoverned.

When an agent can deploy code, mutate data, or touch infrastructure, you need more than tool definitions. You need a governed runtime between the model and the capability.

In this article I’ll outline what a governed, protocol‑neutral runtime does, why it matters for AI agents, and how it differs from agent frameworks and tool protocols.

Start from capabilities, not protocols

In many stacks, the starting point is the protocol surface: an HTTP API, a CLI, an MCP server, or a bespoke RPC layer. Governance ends up scattered across them.

A governed runtime inverts this. The primitive is a capability:

a function your system can perform
with a strict input/output schema
annotated with metadata and policies

Protocols become adapters that project that same capability to different callers.

Enforce strict contracts at the edge

LLMs are probabilistic. They will:

omit required fields
invent parameters
send values in the wrong shape

If you only validate deep inside application code, you pay for side effects and partial failures before discovering the problem.

A governed runtime enforces contracts before execution:

validate inputs against a schema
validate outputs before returning
guarantee error shapes so callers can rely on them

This is just as important for human‑driven CLI or HTTP calls as it is for agents.

Centralize governance semantics

When every surface (CLI, HTTP, MCP, a2a) re‑implements:

ACL checks
approval workflows
environment / tenant routing
logging and policy hooks

…you end up with drift and blind spots.

A runtime should provide a single pipeline where it can apply:

identity and ACL resolution
approval gates for high‑risk actions
call‑chain guards (who called on behalf of whom)
middleware for custom policies and observability

Adapters then plug into that pipeline, instead of embedding their own partial implementation.

Make execution observable by default

Governed systems need more than a log line. They need structured evidence.

A runtime can emit:

structured errors tied to capability IDs
trace context that spans agent reasoning and execution
events (started, retried, completed, failed)
usage hooks suitable for metrics and billing

That makes capabilities safe to expose through multiple channels, because you can audit and debug behavior no matter who called them.

Separate reasoning from orchestration

Agent frameworks excel at planning and choosing tools, not at guaranteeing exactly‑once execution across a fleet of workers.

A robust design pairs the governed runtime with a workflow / orchestration layer that handles:

distributed task execution
retries, backoff, and idempotency
timeouts and cancellation
compensation logic

The agent chooses; the runtime and orchestrator guarantee how.

Stay protocol‑neutral

Today’s hot protocol is MCP. Tomorrow it might be something else.

If all your semantics live in one protocol layer, you’re locked in. A protocol‑neutral runtime keeps your:

schemas
governance
execution semantics

…independent of any single protocol. MCP, a2a bridges, CLIs, HTTP APIs, and in‑process calls all project the same capability definition.

What to look for in a governed agent runtime

When you evaluate libraries and platforms, ask:

Where do capability contracts live, and are they language‑agnostic?
How are identity, ACLs, and approvals enforced?
Can I expose the same capability to MCP, HTTP, CLI, and internal code without rewriting logic?
What structured evidence do I get when something goes wrong?

A runtime that answers those questions cleanly will make your agents safer, more debuggable, and easier to operate in production than yet another pile of glue code between an LLM and your systems.

Cross-Language SDKs for a Single Agent Capability Standard

tercel — Thu, 10 Sep 2026 08:05:30 +0000

In most real-world systems, “AI agents” sit on top of a polyglot stack:

Python for data and ML
TypeScript/Node for backend and APIs
Rust/Go for performance-sensitive pieces

If your capability model only really exists in one language, you end up with:

Duplicate logic in other languages
Inconsistent validation and error handling
Governance rules that only apply to the Python part

A more sustainable pattern is to treat the capability protocol as the primary artifact and the language SDKs as implementations.

Concretely:

Specify a wire-level protocol and schema format.
Define how metadata (risk, cost, ownership) and governance hooks (ACL, approvals, audit) attach to a capability.
Build SDKs in your target languages that:
- Use the same conformance tests
- Expose idiomatic APIs
- Produce identical runtime behavior

Now a capability implemented in Rust can be:

Called by a Python-based agent
Exposed as an HTTP endpoint by a TypeScript service
Invoked via CLI by ops teams

…without reinventing validation, approvals, or tracing.

If you are designing your own internal runtime, consider starting with the protocol and tests first, and only then layering language-specific ergonomics on top. It is slower upfront but pays off when your stack inevitably becomes polyglot.

Designing Directory-as-ID for AI-Discoverable Capabilities

tercel — Thu, 03 Sep 2026 05:11:23 +0000

Capability discovery is one of those problems that quietly gets solved five different ways in the same company.

For AI agents it matters even more: if you cannot reliably discover and describe your own capabilities, models will not either.

A simple, robust pattern is directory-as-ID:

The directory path on disk is the capability identifier.
A schema + metadata file live alongside the implementation.
The runtime walks the tree to build a catalog.

Why this helps:

Natural for developers

Your repo already uses directory structure to organize concepts. Making it the capability ID means git diff, code review, and grep remain your primary tools.
Good for governance

ACLs and approval rules can be attached at directory boundaries (e.g., payments/* requires stronger checks than analytics/*).
Legible to AI systems

Models (or offline indexers) can infer semantics from stable paths and read schemas/metadata without custom discovery code.

A minimal implementation looks like:

capabilities/ payments/charge/ schema.json metadata.yaml implementation.py

Your runtime:

Recursively walks capabilities/.
Loads schema + metadata.
Registers the capability under the directory path as ID.

From there you can project the same capability into MCP tools, HTTP endpoints, CLIs, or direct imports—with governance hanging off the catalog instead of scattered across services.

If you are wrestling with “how do I let agents discover what they can safely do?”, directory-as-ID is a surprisingly powerful starting constraint.

Why Your AI Agent Keeps Calling the Wrong Tool (and How to Fix It)

tercel — Tue, 01 Sep 2026 01:24:47 +0000

It’s Friday afternoon. You’ve just deployed a sophisticated AI Agent with a suite of 50 enterprise tools. Five minutes later, the logs show a disaster: the Agent was supposed to deactivate_user for a support ticket, but instead, it hallucinated and called delete_user.
Why? Because the text descriptions were "too similar," and the LLM felt lucky.
If you’ve spent any time building Agentic systems, you know this pain. We’ve been building mission-critical automation on top of "Vibes"—fuzzy string descriptions and loose JSON objects.
Let’s look at why traditional tool-calling is failing and how we can move toward a world of AI-Perceivable modules.The "Vibe-Based" Engineering Crisis

On the surface, this looks fine. But as your system scales from 5 tools to 50 or 500, several critical failure points emerge:- Description Overlap: If you have remove_user, delete_account, and deactivate_member, the LLM often picks the wrong one based on a slight nuance in the user's prompt.

No Behavioral Context: Does the AI know that delete_user is a destructive operation that should require human approval? No. It just sees a string.
The Validation Gap: Traditional tools are often "fire and forget." If the AI passes a malformed ID, the system throws a generic 500 error, and the Agent gets stuck in a loop.

We are essentially trying to "Prompt Engineer" our way into reliable software. That is not engineering; that’s hope.Introducing apcore: The AI-Perceivable Standard
At apcore, we believe that if a module is to be invoked by an AI, it must be AI-Perceivable. This means the module must explicitly communicate its structure, its behavior, and its constraints in a way that the AI doesn't have to "guess."
Let's look at the same delete_user tool implemented as an apcore module in Python:
from apcore import Module, ModuleAnnotations, Context
from pydantic import BaseModel,
Why this is a game-changer:- Dual-Layered Intelligence: We separate the description (short, for discovery) from the documentation (long, for detailed planning). The AI only reads the "manual" when it's actually considering using the tool.

Behavioral Guardrails: By marking a module as destructive, we give the LLM a cognitive "stop sign." It knows it shouldn't just run this autonomously.
Strict Enforcement: In apcore, you cannot register a module without a valid schema. It turns "AI-Perceivability" from a best practice into a protocol requirement. The Secret Sauce: ai_guidance What happens when the AI does make a mistake? In traditional systems, you get a traceback. In apcore, we use Self-Healing Guidance. If an Agent sends a numeric ID instead of a UUID to our delete_user module, apcore doesn't just crash. It returns a structured error:

The Agent reads the ai_guidance, realizes its mistake, fetches the correct UUID, and retries—autonomously. This is the path to truly resilient Agentic systems.Conclusion: Stop Prompting, Start Engineering

Type-Safe Agents: Leveraging apcore-js in TypeScript

tercel — Sat, 06 Jun 2026 12:32:25 +0000

While Python dominates the AI research space, TypeScript is the engine of the modern full-stack web. From high-performance Node.js backends to complex React frontends, TypeScript provides the structure and safety that large-scale engineering teams demand.

When we built the apcore-js SDK, we didn't just want to "port" the Python logic. We wanted to create a first-class, type-safe experience that leverages the unique strengths of the JavaScript ecosystem.

In this twentieth article of our series, we explore how to build AI-Perceivable modules in TypeScript using apcore and TypeBox.

The Goal: Cross-Language Parity

A core tenet of the apcore protocol is that a module’s behavior should be identical regardless of the implementation language. A module named executor.user.get must accept the same JSON input and produce the same output in both Python and TypeScript.

apcore-js achieves this by using TypeBox as its core schema engine. TypeBox allows us to define JSON Schemas that double as TypeScript types, giving us compile-time safety and runtime validation in a single definition.

Defining Type-Safe Schemas

In apcore-js, you define your module's contract using TypeBox's Static and Type primitives:

import { Type, Static } from '@sinclair/typebox';

export const InputSchema = Type.Object({
  userId: Type.String({ description: "The unique UUID of the user." }),
  includePrivate: Type.Boolean({ default: false, description: "Whether to include sensitive fields." })
});

export type Input = Static<typeof InputSchema>;

By adding the description field directly into the TypeBox definition, you are creating the "Cognitive Interface" for the AI while simultaneously providing type hints for your IDE.

Building the Module

apcore-js supports both class-based and functional module definitions. The class-based approach is idiomatic for TypeScript developers:

import { ClassModule, ModuleAnnotations, Context } from '@apcore/core';

export class GetUserModule extends ClassModule {
  id = "executor.user.get";
  description = "Retrieve detailed user profiles.";
  inputSchema = InputSchema;

  annotations = new ModuleAnnotations({
    readonly: true,
    destructive: false
  });

  async execute(inputs: Input, context: Context): Promise<object> {
    // inputs is fully typed!
    const user = await db.users.findUnique({ where: { id: inputs.userId } });
    return { status: "success", user };
  }
}

Automated Discovery & Mapping

Managing a registry in Node.js is just as easy as in Python. apcore-js includes a FileSystemLoader that scans your directory structure.

One of the cleverest parts of the SDK is its Automatic ID Normalization. In TypeScript, it’s common to name your files using camelCase (e.g., sendEmail.ts). apcore-js automatically maps this to the canonical snake_case (e.g., send_email) required by the protocol. This ensures that an AI Agent sees a consistent naming convention even in a polyglot environment.

Trace Propagation in the Node Mesh

AI Agents in the Node ecosystem often live inside microservices. apcore-js is built for distributed environments. It automatically propagates the trace_id through Promise chains and can integrate with existing tracing headers (like Zipkin or Jaeger) via custom middleware.

const result = await executor.callAsync("executor.user.get", { userId: "123" }, context);

Conclusion: Reliability at Compile Time

By combining the rigor of the apcore protocol with the safety of TypeScript and TypeBox, apcore-js allows you to build AI-Perceivable systems that are as reliable as they are intelligent. You get the best of both worlds: high-velocity development and rock-solid architectural constraints.

Now that we’ve mastered the two most popular languages for AI, it’s time to look at the performance tier. In our next article, we dive into Zero-Cost Abstraction: Building High-Performance AI Modules in Rust.

This is Article #20 of the **Building the AI-Perceivable World* series. Type safety is the first step to AI safety.*

GitHub: aiperceivable/apcore-typescript

Pythonic AI: Mastering the apcore-python SDK

tercel — Wed, 03 Jun 2026 12:36:55 +0000

Python is the undisputed language of the AI era. It’s the language of research, the language of LLM orchestration (LangChain, CrewAI), and for many, the language of the enterprise backend.

When we designed the apcore-python SDK, our goal was simple: High Perceptibility, Low Intrusion. We wanted to give Python developers a way to make their code "AI-ready" without forcing them to rewrite their entire architecture.

In this nineteenth article of our series, we move from the engine room to the keyboard, showing you how to master the Python SDK to build professional, AI-Perceivable modules.

Defining Modules: The Two Styles

Every developer has a different preference. Some love the structure of classes; others prefer the simplicity of decorators. apcore supports both.

1. The Decorator Style (Fast & Functional)

If you have an existing utility function and you want to turn it into an AI "Skill" in 30 seconds, use the @module decorator.

from apcore import module

@module(id="text.summarize", description="Summarize text for Agentic planning.")
def summarize(text: str, length: int = 100) -> dict:
    # Your logic here...
    return {"summary": "..."}

2. The Class Style (Structured & Extensible)

For modules that require complex state, custom initialization, or detailed behavioral annotations, the class-based approach is superior.

from apcore import Module, ModuleAnnotations, Context
from pydantic import BaseModel

class SendEmailInput(BaseModel):
    to: str
    body: str

class SendEmailModule(Module):
    input_schema = SendEmailInput
    description = "Send secure internal emails."
    annotations = ModuleAnnotations(destructive=False, requires_approval=True)

    def execute(self, inputs: dict, context: Context) -> dict:
        # Business logic...
        return {"status": "sent"}

Pydantic Integration: The Secret Weapon

The "Killer Feature" of apcore-python is its deep integration with Pydantic V2.

In the AI world, your schema's description fields are just as important as the types. apcore-python extracts these descriptions directly from your Pydantic models.

class SearchInput(BaseModel):
    query: str = Field(..., description="The search term. Use keywords, not sentences.")
    limit: int = Field(5, description="Max results to return.")

When you register this module, apcore automatically generates a JSON Schema Draft 2020-12 that includes these descriptions. This ensures that the AI Agent knows exactly how to use each parameter.

Initializing the Core

Starting with v0.18.0, we’ve simplified the APCore constructor to focus on a unified configuration model. You no longer pass multiple paths to the constructor; instead, you load a Config object.

from apcore import APCore, Config

# Load config from apcore.yaml and initialize
config = Config.load("apcore.yaml")
app = APCore(config=config)

This ensures that your security policies, pipeline steps, and registry settings are always in sync across your entire application.

Execution & Async Support

AI Agents are often used in asynchronous environments (web servers, background tasks). The apcore-python SDK is built for this. You can call modules synchronously or asynchronously with full trace propagation.

executor = Executor(registry)

# Async execution with identity propagation
result = await executor.call_async(
    "text.summarize", 
    inputs={"text": "..."}, 
    context=context
)

Conclusion: Built for Developers, Ready for AI

apcore-python isn't just a library; it’s a design pattern. It allows you to build software that is idiomatic for Python developers and perfectly perceivable by AI Agents. By combining the power of Pydantic with the rigor of the apcore protocol, you are building the foundation for a reliable Agentic workforce.

Now that we’ve mastered Python, it’s time to look at the other side of the stack. In our next article, we dive into Type-Safe Agents: Leveraging apcore-js in TypeScript.

This is Article #19 of the **Building the AI-Perceivable World* series. Idiomatic code is the bridge to better AI.*

GitHub: aiperceivable/apcore-python