Building an Agentic Operating System for Commodities

The architecture behind event-driven workflows, job-scoped agents, and controlled execution

A trade instruction arrives by email containing commercial terms, a counterparty reference, and dependencies on broader business context. Hours later, a follow-up message amends the agreement. Turning these unstructured messages into operational records requires interpreting intent, matching existing trades, spotting missing fields, and routing for approval.

Automating this requires a system that can reason over unstructured documents, pull business context, and stage updates within an established process. For enterprise IT teams, the architecture must also make clear where workloads run, how access is scoped, how failures are handled, and where control hands off to systems of record.

CommodityAI has created an agentic operating system for physical commodities. Our architecture pairs deterministic workflow transitions with AI agents that reason within bounded jobs. These agent jobs are triggered by events. Each agent job has clear goals and a set of tools supplied with human review when the job requires it.

Following a trade from instruction to approval

When a trade message arrives, an agent evaluates whether it is a new trade or an amendment, pulls relevant records, and drafts an entry for the trader to review. Once captured, configured rules determine whether the trade requires manager approval. If so, a separate agent job compiles an approval brief with counterparty history, credit exposure, and overdue payment data.

This division of labor defines our architecture: agents handle the variable, context-dependent work of gathering and synthesizing data, while the surrounding workflow enforces the operational sequence and human control points.

Giving agents a consistent view of the business

Commodity businesses run similar commercial processes across disparate legacy schemas. Deploying an agent starts with mapping customer records into their custom representation that the agent can query reliably.

CommodityAI maintains structured records for core objects (trades, counterparties, shipments, products) alongside unstructured contracts and documents. Agents use dedicated tools to query only the context relevant to their goal. A trade-capture agent pulls product and pricing data; an approval agent queries credit and exposure records.

Figure 1. Logical customer environment and service connections. CommodityAI operates within the customer’s logical environment; this diagram illustrates service boundaries rather than physical hosting or network isolation.

This unified data model anchors agent reasoning. Historical trades help an agent spot missing fields or unusual terms to flag for human review, without treating past trades as authoritative for a new agreement. Mapping this model during implementation establishes both the context available to agents and the synchronization boundaries with existing systems.

Defined transitions with flexible reasoning inside each agent job

CommodityAI supports agent-driven workflows throughout the trade lifecycle. Figure 2 shows one highly simplified example, from trade capture through approval, to illustrate how agent jobs, workflow rules, and human decisions fit together.

Operational triggers and approval thresholds belong in deterministic configuration. Resolving ambiguous counterparty references or assembling a complex approval brief requires flexible reasoning.

We separate these concerns cleanly. The workflow engine dictates which job runs next. Inside a job, the agent invokes tools, inspects results, and gathers context to achieve its goal before handing off to the next configured step or a human reviewer.

Figure 2. One highly simplified trade-capture and approval workflow, illustrating the architecture used across the broader trade lifecycle.

This keeps the overall process predictable and auditable while preserving flexibility where it counts. An agent can adapt how it investigates a specific trade, while the approval requirement remains a fixed workflow rule.

Scoping what each agent can do

Read and write permissions are scoped at the tool level. Each tool defines the data access and operations available through it. Assembling an approval brief requires different capabilities than drafting a trade record, so the execution environment supplies each agent job with the tools and access it needs.

Validation and human review boundaries

When an agent proposes an operation, the system validates it against application and API rules, returning actionable error feedback so the agent can revise rejected attempts. However, API validation only verifies structural correctness, not commercial intent.

For example, when a trader confirms a proposed trade record, configured rules determine whether manager approval is required. If it is, an agent gathers counterparty history, credit exposure, and overdue payment data into an approval brief. The trade manager reviews that evidence and makes the approval decision; preparing the brief does not authorize the trade.

Execution and data isolation

Each agent job runs in an isolated execution environment with job-specific tools. For example, an approval-brief job can receive tools to read counterparty and exposure records without receiving a tool to change trade terms. Read access does not confer write permission. This supports the enterprise principle of least privilege: reviewers can inspect each tool’s permitted reads and writes, separately from the infrastructure that isolates job execution.

Persisted job state and asynchronous execution

Asynchronous workflows triggered by incoming emails require multiple model calls and record lookups, demanding a different execution model than low-latency interactive queries. We route background workloads through a persisted, queue-backed execution engine where each job has a discrete goal and completion state.

Persisting job state allows background jobs to complete, fail, or retry independently without relying on an active user session. It also gives operators a compact unit of work to inspect and debug rather than an entire trade lifecycle.

Connecting to enterprise systems with clear ownership

CommodityAI exposes an authenticated API to connect with existing trading, accounting, and enterprise systems. Because internal execution guarantees do not automatically extend to external connectors, customer- or partner-built integrations must handle delivery, error recovery, and reconciliation. Every implementation explicitly defines the system of record for each field, how updates propagate, and who owns remediation if synchronization fails.

Testing quality beyond valid API requests

While runtime checks validate individual API requests, our offline evaluation suite benchmarks end-to-end extraction accuracy, record matching, and context gathering across representative datasets. Systematic evaluations verify whether system changes improve performance and allow us to match jobs to the right model based on empirical quality, latency, and cost rather than assuming one model fits every stage.

The design principle behind the platform

CommodityAI’s architecture mirrors physical commodity operations:

• Events initiate work.
• Agents gather context and reason through bounded jobs.
• Application rules validate operations and govern workflow transitions.
• People review proposals and make commercial decisions.
• APIs synchronize outcomes with the surrounding enterprise.

Combining job-scoped AI with deterministic workflow boundaries lets enterprise teams automate variable, context-heavy work inside an auditable operational structure.