> ## 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
> How ACI treats AI agents as first-class operators with identity, workspaces, validation, and audit trails.
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:
| Property | Human Principal | Agent Principal |
| -------------- | ---------------------- | -------------------------- |
| Identity | SSO / email | API key / service identity |
| Authentication | OIDC provider | API credentials |
| Workspace | Draft workspace | Draft workspace |
| Saved versions | Attributed to the user | Attributed to the agent |
| Audit trail | Full history | Full history |
| Validation | Content compiler | Content 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:
```mermaid theme={null}
sequenceDiagram
participant Agent
participant ACI
participant Compiler
participant Reviewer
Agent->>ACI: Create draft workspace
ACI->>Agent: Workspace ready
loop For each change
Agent->>ACI: Write content to workspace
ACI->>Agent: Version saved
end
Agent->>ACI: Request preview
ACI->>Agent: Rendered HTML
Agent->>ACI: Submit for merge
ACI->>Compiler: Validate full site
Compiler->>ACI: Validation passed
ACI->>Reviewer: Review requested
Reviewer->>ACI: Approved
ACI->>ACI: Merge to main
```
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 content from any workspace. Write content to draft workspaces. Create new pages, update existing ones, or delete content, all through structured API calls.
Create draft workspaces, save changes, and submit for merge. Agents manage their own workspaces the same way a developer manages parallel projects.
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.
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 for local site validation and API-backed branch/content workflows:
```bash theme={null}
# Create a branch and start working
aci branch create agent-seo-optimization
# Clone the content paths the agent needs
aci content clone agent-seo-optimization ./workspace-seo \
--path /pages/home/_index.json
# Edit files locally, then push the workspace changes
aci content push ./workspace-seo
# Rebase and land through the API
aci branch rebase agent-seo-optimization --target-ref main
aci branch land agent-seo-optimization --target-ref main
```
Local frontend validation uses the build command:
```bash theme={null}
aci doctor
aci build --compile-only
aci build --skip-code --content ./.content --out ./.aci/compiled
```
API-backed branch and content commands use the same versioning engine underneath. Local build commands validate the same frontend contract and content shape before those changes are synced or published.
## Git Workspaces: The Native Agent Interface
ACI gives agents a **real Git repository**.
ACI is built around the Git-native workspace model described below. Today, agents reach it through `aci content clone`, `aci content push`, and the `aci branch` commands, with the full hydrate-and-submit workspace experience expanding from there.
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.
```mermaid theme={null}
sequenceDiagram
participant Agent as AI Agent
participant ACI as ACI Engine
participant WS as Git Workspace
Agent->>ACI: Start task: optimize product pages
ACI->>WS: Create sparse checkout
(47 files, scoped history)
WS->>Agent: /workspace with .git
loop Edit cycle
Agent->>WS: Read/write JSON files
Agent->>WS: git diff, git commit
end
Agent->>WS: Need /config/nav.json too
ACI->>WS: Hydrate path (preserves work)
Agent->>ACI: aci workspace submit
ACI->>ACI: Validate → merge to main
```
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.
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.
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.
`git diff`, `git log`, `git commit` all work. Any Git-compatible tool works. No proprietary SDK required.
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](/aci/architecture/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 →](/aci/developers/frontend-contract)*