Agentao: The Runtime That Makes Agentic Power Governable
Agentao is an embeddable Python runtime for building agents that can use tools, retain state, and interact with a host application. The central question is not whether a language model can produce a convincing answer; it is how a host can let a model propose actions without surrendering control of capability, state, or consequences. This series develops a practical way to judge that question: understand what Agentao governs, what the host must still own, and where the boundary must move outward to the operating system or network.
That framing matters because “agent” is often used to describe several different things at once. It can mean a model with a long prompt, a tool-calling loop, a chatbot product, or an entire application that includes identity, data access, and a user interface. Agentao’s documentation makes a narrower claim. It describes Agentao as a governed runtime: the part that coordinates an LLM loop, tools, permissions, memory, protocols, and sessions. The host application supplies the business muscles around it—its users, APIs, database, interface, and deployment policy.
The problem is not generating text
A plain chat completion has a relatively clean boundary. The application sends context and receives text. An agent changes the shape of the system because the model can propose a sequence of actions: read a file, call a business API, run a command, fetch a page, save a memory, or ask a human for a decision. The useful answer may be distributed across several tool calls rather than contained in the first model response.
That capability creates a second engineering problem. Someone must decide which actions are available, whether a particular call is allowed, how the user can approve a risky step, what state survives a restart, and how an operator can later explain what happened. A prompt can describe the desired behavior, but it does not by itself enforce filesystem boundaries, tenant identity, network egress, or business authorization. If those responsibilities remain implicit, the system may look simple while its authority is not.
Agentao’s value proposition is therefore less “add intelligence to an application” than “make the moving parts of an agent explicit enough to embed and govern.” Its project documentation groups that design around constraint, connectivity, and observability. Permissions and confirmation constrain action; MCP, ACP, plugins, and related protocols connect the runtime to hosts and external capabilities; events, logs, and replay show the work. These are not independent decorations. A tool without a policy is an exposed action. A policy without an event trail is difficult to inspect. A stateful session without a clear owner is a data-isolation problem.
The project is not an end-user assistant with its own identity system, billing model, or product UI. Nor is it simply a toolkit for composing arbitrary components. It is a preassembled runtime that a host can call directly from Python or drive through the Agent Client Protocol, while retaining responsibility for the application around it. That distinction prevents a common category error: treating an agent runtime as if it were the whole product.
The boundary becomes clearer in a concrete product. Imagine a project-management service where a user asks an assistant to summarize open work and create a task. Agentao can coordinate the reasoning and expose a list_projects capability, but the host should construct that capability with the tenant identity already attached. The model may choose a project and propose a title; it should not be trusted to invent the tenant that authorizes the API request. Creating the task may pass through a permission rule or a confirmation callback, while the business API remains responsible for checking whether the user can actually create it. Agentao is useful here because it gives the host a place to coordinate the proposal, the policy decision, the tool result, and the visible response. It does not remove the host's obligation to enforce the business rule.
The same runtime looks different in an editor. A plugin written in another language can run Agentao as an ACP subprocess. The editor receives streamed updates, turns a permission request into a modal, and decides how to recover if the child process exits. The model still proposes, and Agentao still mediates the loop, but the process boundary changes who must parse messages, correlate requests, and persist or reload the session. In an unattended nightly job, the human approval step may not exist at all. The host must then narrow the tools and use explicit allow/deny policy rather than assuming that a missing approval UI is equivalent to consent. These are not three different definitions of Agentao; they are three placements of responsibility around the same runtime.
This is also why “local-first” and “private-first” should be read as architectural tendencies rather than security guarantees. Keeping the runtime close to the host can reduce the number of mandatory services and give the application direct control over inputs, files, logs, and credentials. But local execution can also enlarge the blast radius if the host exposes a powerful shell or shares a working directory across tenants. Privacy depends on how the host scopes memory, subprocess environments, logs, and network access. The design makes those choices available; it cannot make a careless choice safe by naming it private.
The useful promise, then, is not unrestricted autonomy. It is legible autonomy: a model can plan and adapt across several steps, while the surrounding system makes the capability surface, policy decisions, state ownership, and evidence paths visible. That is a more demanding design than adding a chat box, but it is also what lets an agent participate in a real application without making every consequence invisible.
The diagram is deliberately asymmetric. The model proposes; it does not own the whole action path. Agentao mediates the loop and exposes policy surfaces, but the host still decides how identity and business rules attach to tools. The operating system and network can impose constraints that a model-facing instruction cannot. The event and audit paths return evidence to the host, which is what makes governance more than a promise hidden in a system prompt.
Six pieces, one system
Agentao’s developer guide introduces six concepts that are easy to confuse if they are learned as a feature list rather than as responsibilities.
An Agentao instance is a stateful, single-session object. It owns the conversation history, tool registry, skill manager, memory manager, and one working directory. One instance is not a shared “brain” for arbitrary users. In a multi-session application, the host constructs a separate instance for each session and serializes turns that use the same instance.
A Tool is an executable capability. It has a name, a description visible to the model, a parameter schema, and an implementation. A host can wrap a business API as a tool, but the tool should carry the tenant or user context from its construction rather than asking the model to supply an authority-bearing identifier. A tool can also declare whether it requires confirmation or is read-only. The description helps the model choose; it is not a substitute for server-side validation.
A Skill is different. It is a Markdown instruction bundle, usually activated only when its trigger matches the task. It can teach a workflow, tone, or domain convention, and it can point to reference material that the model loads when needed. A skill changes how the model approaches work; it does not create a new executable capability. “Use the approved refund policy” belongs in a skill. “Send a refund request to the billing system” belongs behind a controlled tool.
Transport is the host bridge. It carries one-way events such as streamed model text and tool progress, but it also exposes blocking decisions: whether a tool may run, what answer to return when the agent asks the user, and what to do when an iteration cap is reached. This is where a terminal prompt, a web approval modal, or an unattended policy connects to the runtime. Because confirmation is synchronous from the agent’s point of view, a broken host bridge can freeze the whole turn.
The session and working directory bind time and place. The session is the lifetime of one conversation. The working directory is the project root used by file tools, shell tools, skills, project instructions, memory, and logs. Passing it explicitly is a correctness and isolation requirement in a server: relying on a process-wide current directory allows otherwise separate sessions to see the same state.
Finally, the system prompt is dynamic. Agentao rebuilds it on each chat turn from project instructions, runtime capabilities, current skills, memory, task state, and other context. This makes it possible to keep stable project constraints separate from per-turn recall, but it also means the host should not treat the prompt as a static artifact that can safely replace every other control. The prompt tells the model how to behave; the runtime and host decide what the model can cause.
Governance is an allocation of authority
The most useful way to understand Agentao is to ask three questions about every action.
First, what may the model propose? The available tool schema, skill catalog, project instructions, and conversation context shape its proposal. Reducing the visible tool set is valuable because unnecessary capability creates unnecessary attack surface. But hiding a tool from the model is not the same as authorizing or denying it for a tenant.
Second, what does the runtime mediate? Agentao can route a proposed call through permission rules, request confirmation, bind it to a session’s capabilities, emit lifecycle events, and feed the result back into the next model iteration. It can persist or recall memory, compress context, and stop a loop that exceeds a configured budget. These mechanisms make action visible and interruptible, but they still operate within the capabilities the host has supplied.
Third, what must the host or infrastructure enforce? Business access control, tenant identity, credential scope, container boundaries, network egress, and retention policy do not become reliable merely because the model was instructed to respect them. Agentao’s own security guidance describes defense in depth for precisely this reason. Prompt-injection resistance is useful; it is not a replacement for a permission gate. A domain blocklist is useful; it is not a replacement for an egress firewall. A separate working directory is useful; it is not a complete operating-system sandbox.
This allocation also explains why the project exposes both rich internal events and a more stable host contract. A streaming interface can change as the runtime gains better details for a user interface. An audit pipeline needs a narrower, schema-controlled projection of tool, permission, and sub-agent lifecycle. The host has to choose the surface according to the consequence of change, not according to which API is easiest to print to a console.
The same reasoning will guide the rest of this series. The next step is to follow one request through an Agentao session: construction, prompt assembly, model iteration, tool execution, host decisions, state, and cleanup. Once that loop is clear, the choice between an in-process Python SDK and an ACP subprocess becomes a choice about where to place responsibility—not just a choice between two connection syntaxes.