Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gradial.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Agent-Native Design

Content platforms are adding AI features: text generation sidebars, summarization buttons, copilots that suggest changes but cannot make them. Agentic Content Infrastructure (ACI) takes a fundamentally different approach. AI agents are operators. They authenticate, they get their own workspaces, they save changes, they go through validation, and their work is fully traceable. This is what makes it possible to run agent workflows at scale without sacrificing governance. The foundation is a file-based data model. All content in ACI is typed JSON files in a directory structure. Agents don’t need to reason through a maze of proprietary APIs, query languages, or platform-specific abstractions. They read JSON, edit JSON, and write JSON. This is exactly what LLMs excel at, and it means any AI coding agent can operate on ACI content with zero custom integration.

​
Agents as Principals

In ACI, every operator, whether human or agent, is a principal with an identity. An agent principal has the same structural properties as a human principal:
PropertyHuman PrincipalAgent Principal
IdentitySSO / emailAPI key / service identity
AuthenticationOIDC providerAPI credentials
WorkspaceDraft workspaceDraft workspace
Saved versionsAttributed to the userAttributed to the agent
Audit trailFull historyFull history
ValidationContent compilerContent compiler
There is no “agent mode” or “AI sidebar.” The infrastructure is the same. The validation pipeline is the same. The audit trail is the same. The only difference is how the principal authenticates.
This design means governance rules work for agents automatically. If your approval policy requires a human to review changes to legal pages, that rule applies whether the change was made by a person or an agent. No separate “AI governance” layer needed.

​
The Agent Workflow

A typical agent workflow looks like this: The agent works in its own workspace. It can make as many changes as needed, drafting pages, updating fragments, generating variants. At any point, it can preview the results. When the work is ready, it submits for merge, and the content goes through the same validation and review pipeline as any human edit.

​
What Agents Can Do

ACI provides a complete API surface for agents to operate through. Agents can:

Read and Write Content

Read content from any workspace. Write content to draft workspaces. Create new pages, update existing ones, or delete content, all through structured API calls.

Create Workspaces and Publish

Create draft workspaces, save changes, and submit for merge. Agents manage their own workspaces the same way a developer manages parallel projects.

Preview Changes

Request a preview of any page in any workspace. Agents can verify their work looks correct before submitting for review, enabling visual QA without human intervention.

Query the Content Graph

Find pages by content type, query the dependency graph, discover which pages use a specific fragment. This lets agents make targeted, informed changes across a site.

​
The CLI Interface

For agents that work in a shell environment, ACI provides a CLI that exposes the full content workflow: 
# Create a branch and start working
aci branch create agent/seo-optimization

# Write content
aci content write /pages/home.json --branch agent/seo-optimization

# Preview a page
aci preview /pages/home.json --branch agent/seo-optimization

# Validate the branch
aci compile --branch agent/seo-optimization

# Submit for merge
aci merge agent/seo-optimization --to main
The CLI uses the same versioning engine underneath. Every command creates versions, follows validation rules, and generates audit events.

​
Git Workspaces: The Native Agent Interface

ACI gives agents a real Git repository. When an agent starts a task, ACI projects the relevant content into a sparse Git checkout, a real .git directory with real versions, real history, and full compatibility with any Git tooling. The agent works with JSON files on a filesystem, exactly the way AI coding assistants already work. This is the key insight: agents don’t need a content API; they need a filesystem and Git. LLMs are trained on code. They understand files, directories, JSON, and version control. ACI meets them where they are.

Sparse Checkout

Agent receives only the files it needs, such as a product page and its referenced fragments. Not 50,000 files. Keeps the context window focused and efficient.

On-Demand Hydration

Need a file that wasn’t in the initial checkout? ACI adds it to the workspace with its history, without disrupting the agent’s in-progress work.

Standard Tooling

git diff, git log, git commit all work. Any Git-compatible tool works. No proprietary SDK required.

Safe Submission

Changes are submitted back through the ACI control plane. Same validation, same compilation, same audit trail as any other content change.
For more detail on how workspaces are projected and hydrated, see Content Versioning → Real Git Workspaces.

​
Agent + Gradial Platform

ACI provides the infrastructure for agent operations. Gradial’s agent platform provides the agents themselves, specialized AI operators for content tasks:
  • Drafting agents that generate pages, fragments, and copy
  • Optimization agents that improve SEO, accessibility, and performance
  • Translation agents that produce locale-specific content variants
  • QA agents that audit content for brand compliance, accessibility, and accuracy
Each Gradial agent operates as a typed principal in ACI. The customer controls which agents have access, what roles they can assume, and what content they can modify. Gradial agents follow the same governance rules as any other operator. You can also build your own agents against ACI’s API. The platform is not limited to Gradial’s agent catalog.
Next: Frontend Contract →