Thoughts on Designing an Agent Platform

This is the English version of Agent Platform 的设计思考.

Background

The Agent Platforms on the market today — Hermes, OpenClaw, CodeBuddy, CatPaw — all look basically the same: MCP, Channel, Skill, Job, and so on.

When we set out to build an Agent Platform of our own, it is hard to escape the shackles of that same design.

But for a B2B enterprise Agent Platform, setting aside everything I just listed, I think the parts that can actually be differentiated are these:

1. The ability to integrate with vertical, industry-specific products
2. Having a vertical, industry-specific knowledge base
3. Binding the memory a user accumulates through use
4. Enterprise governance capability
5. Self-iteration (at the task level)
6. Cloud–local collaboration

1–3 are obvious, and they depend heavily on data and domain knowledge.

But an Agent platform that has enterprise governance, self-iteration and cloud–local collaboration at the same time barely exists on the market.

In short

How do we solve permissions and roles for Agents? (enterprise governance)

See “Opinion 2: All permissions should be delivered as Auth Tokens” below.

Today the vast majority of Agent Platforms only support configuring tools for a single role.

By delivering a complete Agent through the file system, and using Auth Tokens plus container variables, every Agent gets Least Privilege permissions.

Through a customized Pi Agent framework, or through a gateway, we can implement Agent execution-record management.

How do we achieve self-iteration

See “Step 3: Self-reflection” below.

Use A2A to let the Builder Agent and the Runtime Agent collaborate, turning every problem that shows up during a run into an improvement point. Then use a certain amount of process management to keep iterating on the existing Agent.

The value of cloud–local collaboration

See “Step 2: Start the sandbox” below.

In a B2B setting, the company can require employees to install a Local Agent with a certain degree of autonomy. When an Agent running in the cloud hits an insufficient-permission problem, the employee needs to authorize locally, find the corresponding credentials — a browser session, say, or a token obtained after authorization — and send them to the Agent on the cloud side.

What kind of Agent is a good fit for running on an Agent Platform?

Stable, repeatedly executed workflow Agents

• A company has a business that runs steadily over a long period — for example listing a product, which requires pulling data from a specific data source, then image processing, translation, filling in forms and submitting for review.
• The day-to-day work of a particular role: highly standardized roles such as accounting, where the work is approving tabular data, submitting internal forms, and so on.

Agents for data collection, organization, light analysis and light decision-making

A company needs to analyze all kinds of sales data every day, produce reports and light analytical summaries, and give business-optimization suggestions. The Agent takes part by suggesting decisions, rather than directly executing decisions about the reports.

Work in AI-native roles

Work with no existing workflow — end-to-end “question → answer” scenarios.

Assumptions

Setting aside the inertia of conventional back-office system design: can an Agent Platform throw away some industry conventions that currently look “indispensable”?

User-first vs. Agent-first

In traditional back-office software design, for the sake of making things readable and operable for the user (a human), we design complex UI interactions — field linkage on the front end, all kinds of search forms, drag-and-drop flowchart editors. Doing this does raise the rigor of data management on the platform, but “human-readable” severely limits how fast an Agent can be created, and adds complexity to Agent design.

Opinion 1: A large amount of current software-development design can be discarded if it is not required by the Agent.

As for UI — UI being everything that interacts with the user — it should be pulled out of the Agent; the Agent’s execution should be able to exist completely independently of the UI. In other words, when I build an Agent, we want to decouple as much as possible from all the elements of the current back office; the back office only provides a view of the data.

“Human-readable” is a false need in the age of Agents. As long as a piece of work runs stably after being built, we can completely discard the complex work of making it “human-readable”. For example, for defining a workflow, we can describe inputs and outputs in text and drop all flowchart-drawing tools. We can instead describe the flowchart in text, or use text-based flow-rendering tools such as mermaid to communicate with the Agent. Or use AGUI and let the Agent render the text into something readable.

Flowcharts are just one example. Many back-office configuration flows that look mandatory should go the same way: registering MCP, managing memory, configuring data access, and so on.

A clearly defined Agent Scope

In practice, not every task is suited to being done by an Agent. But as models advance, Agents really have started to be capable of the vast majority of repetitive and light-decision tasks. If we want Agents to meet user expectations, we should identify user scenarios carefully, define Agents in the scenarios that fit, and keep probing the boundary of what an Agent can do, expanding it gradually.

Managing user expectations and defining the Agent scope are just as important as building the Agent itself.

Abstracting the Agent at the capability level

When we set out to build an Agent Platform, we should give up the classic abstraction of memory layer / tool layer / model layer, and instead look squarely at this question: what does an Agent need while it runs?

LLM Access

No need to belabor this. What is worth highlighting is that the Agent we build should be able to dispatch to different LLMs.

File System Access

Agent config, SubAgent config, memory, prompts, code, data, Skills — all of it can be put in a folder, and that becomes the complete set of what an Agent is.

Code Execution

Code is language; it too describes the business rigorously in writing.

Users have many custom process rules, and they care about whether the Agent executes strictly according to the process they defined.

Computer Use

For the many systems whose integration capabilities are not that strong, the most direct and simple approach is computer use — which here also includes browser use and CLI.

The trap of Data Access and Web Access

Data Access and Web Access should be covered by code execution. I can allow my Agent to access data by writing a shell script or Python code, rather than handing it the data directly.

Someone will ask: if that is how it works, how do I control the Agent’s permissions? I will go into that in the Agent governance part.

Opinions

Scenario 1: Engineer A has tuned an Agent locally into an ideal state and wants to share it with everyone on the team. Even if they send all of their Agent configuration and skills to their teammates, the teammates still struggle to pick that Agent up quickly.

Scenario 2: An Agent that runs stably in the cloud under user A’s role one day needs to run under user B’s role. We have almost no way to quickly reproduce a new environment and a new Agent based on user B’s role.

Scenario 3: An Agent behaves as expected on its first run. On the second run, because some variables have changed — data, trigger conditions, time, model — it ends up producing a different result.

Opinion 1: A complete, deliverable Agent is an “everything is a file” Agent

Borrowing from the Linux design philosophy “Everything is a file”, I think that when I say I am delivering an Agent, what I deliver is the files inside a folder, and the sum of those files can completely define an Agent.

For Scenario 1, this makes it very easy to share, pass around and iterate on an Agent, and to run it in different execution environments.

Opinion 2: All permissions should be delivered as Auth Tokens

An Auth Token, being a string, can be delivered and configured inside the Agent’s file system; whereas any authorization method that requires a login interaction is hard to deliver to an Agent. This is the key to solving Agent authorization.

Unless we implement a complete authorization automation that can deliver configuration from files into the Agent Runtime — only then can we support all kinds of authorization methods.

For Scenario 2, the permissions in effect during execution are now managed as an environment variable, and every tool can identify the current user’s identity.

Opinion 3: Reuse software engineering practices to solve business problems and raise Agent reliability

See “What the Agent Builder Agent produces” below.

Every practice from Coding Agents can be applied to implementing a business Agent Platform: introduce an Agent Evaluation Framework, introduce unit tests, pipelines, CheckStyle, spec-driven development, and so on, so that what the Agent Builder Agent produces is reliable and verifiable.

Building an Agent

Defining the Agent Builder’s role

In the long run, the Builder will certainly be a domain expert for some business scenario. When they build an Agent, they are only interacting with a model, describing the business scenario in their head, and out of that comes an Agent Team that solves a particular problem. They have vertical domain knowledge, but not necessarily experience working in internet or software development. They know the process very well, but they do not necessarily have much tolerance for the Agent making mistakes. They know the critical points of every business process, but they do not have the ability to debug an Agent. All of the software-engineering side of this should be covered by the model. Two things to highlight, which industry practitioners need to build up gradually through accumulated work experience:

• Logical thinking about program design
• Experience debugging a running program

But in the early phase of rolling out an enterprise Agent Platform, I suggest the Agent Builder be made up of two complementary people, working together with the goal of debugging the Agent Builder Agent.

1. Someone with a reasonable technical background but limited business depth
2. Someone with deep business understanding but a limited technical background

The process of building an Agent

Step 1: Describe the problem, define the goal

Given a certain amount of experience, the Builder can describe the problem clearly and define the goal clearly. Once models have developed to a certain point, they can understand the user’s request well and, based on the resource pool available, propose a suitable execution plan.

The output of this step should be a very concise, logically clear description of the process, or a flowchart. The Builder and the Agent keep talking until both sides are satisfied.

The Agent Platform should have a set of preset Agents that can be matched directly to the user’s request during the conversation between Builder and Agent — for example Deep Research, Data Analysis, or other Agents commonly used in the industry.

Step 2: Define the Agent’s execution plan

This step should draw heavily on business knowledge and produce a reasonable plan for solving the problem.

Step 3: Define the resources the Agent can access

Based on the proposed plan, the Agent configures resource access permissions. For example, if some Agent needs permission to commit to Git, we should require the Builder to configure Git MCP here, or Git code execution, or CLI (computer use).

Note: CLI is not an ideal solution, because its authorization always requires some interaction — unless we have an automated way to deliver from the current file system into the runtime.

The interactions during configuration should all be AGUI: pages generated on demand.

The generated Agent is stored entirely as files in the file system. This contains only the manifest of required credentials, not any credentials (tokens) themselves. The session in which the Agent was created matters just as much, and is also kept in the file system.

Step 4: Define Success Conditions / Exit Conditions

The system should by default force a minimal Exit Condition onto every Agent. The user sets the success conditions according to business needs.

Step 5: Debug the Agent

In a non-sandbox environment, the Agent Builder Agent pre-runs the Agent that was defined, and the user debugs the Agent in a safe QA environment. Just like coding locally: get the flow working end to end, and keep talking to the Builder.

Agent updates and management

If the user has any update to this Agent, they can continue directly from the session in which the Agent was created, and inherit all of the memory.

Agents exist in the system folder by folder. If the user wants visualization, they can interact through AGUI.

None of the development work at the Agent Platform UI level — the authorization flow, skill installation, and so on — should affect the work of the Agent Builder Agent, nor should it affect the operation of existing Agents. The way MCP is integrated is one example.

Agent execution

The Agent execution environment

The Agent’s execution environment must be an isolated sandbox; all of its capabilities are realized through the permission manifest and the tokens it has been granted.

Agent execution steps

Step 1: Trigger

The user triggers the Agent through the Agent UI, or through a job.

Step 2: Start the sandbox

Trigger the sandbox startup pipeline. Based on the user’s information, look up the tokens the system already has and pass them as environment variables for starting the sandbox.

Copy the Agent folder into the execution environment and, if needed, install dependencies.

Go through all the resources the Agent needs in order to run. If some information is missing, fire a webhook and communicate directly with the user over Slack (or with the user’s Local Agent — this is the cloud + local collaboration).

Step 3: Self-reflection

If, during execution, the Agent in the sandbox makes corrections to itself, fire a review notification so the Builder can review it and merge the improved Agent files back into the original files.

Step 4: Shut down the sandbox

Clean up the sandbox according to the level at which it was defined: if the sandbox is at the user level, clean it up after the user has been idle for a while; if the sandbox is at the session level, destroy it when the task ends.

The Agent Builder Agent

For the Agents we build to actually solve business problems and meet enterprise requirements, we should try to reuse software engineering practices to solve business problems and raise Agent reliability.

What the Agent Builder Agent produces

I think what the Agent Builder Agent produces should be an Agent built on top of code. We can use a mature, popular, off-the-shelf Agent SDK — Pi Agent, the Claude Agent SDK, LangChain.

I think that, in order to guarantee that the Agent’s results are trustworthy, repeatable and verifiable, what the Agent Builder Agent builds includes anything that helps us guarantee its quality:

1. Business code
2. Skills
3. Pipelines
4. Prompts
5. Shell scripts
6. …

It can:

• Run inside a sandbox
• Orchestrate the flow autonomously
• Express all credentials as environment variables while running

What is the Agent Builder Agent?

I think the Agent Builder Agent is simply a very capable coding agent:

• It is defined to build an Agent
• It can access a resource pool; it knows all of its own capabilities
• It has a software framework, and that framework requires it to fill the Agent in autonomously, with content drawn from the resource pool
• It has been given a set of coding conventions and self-verification conventions

Defining the resource pool

The resource pool is an abstraction over the set of things an Agent needs. It is abstracted into:

• Type: mcp

  skill

  tool

  llm

  memory

• Description
• Permission
• Verification

What does the software framework define?

Every flow that can be abstracted out can be defined inside the framework: the permission-check flow, the permission-request flow, the Agent’s self-iteration flow, and so on.

Core opinions

1. A delivered Agent must be expressible completely in files
2. The core function of an Agent Platform is the agent that builds agents
3. Differentiating capabilities like enterprise governance, self-iteration and cloud–local collaboration are the main motivation for building your own Agent platform
4. To build an Agent that meets enterprise standards, you need to apply software engineering practices as appropriately as you can, and build the Agent on top of software engineering
5. AGUI should replace the traditional back-office admin page as the primary way of interacting with users