> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subagents VPC Automation
> Guide to splitting VPC automation into an orchestrator plus specialist subagents with least privilege, task delegation, and auditable stateful runs for safe scalable cloud network provisioning
Designing and provisioning cloud networks can quickly overwhelm a single AI agent. This guide shows how to split responsibilities into subagents for safe, auditable, and scalable VPC automation. The approach mirrors a real operations team: one orchestrator coordinating smaller specialists (subagents) with tightly scoped permissions.
Why not one large agent?
* A single agent that handles design, networking, and security accumulates a huge context and needs broad permissions. That increases the blast radius for misconfigurations and makes debugging hard.
* When network topology, firewall rules, and security audits all live in one conversation, unrelated details crowd each other, and authority is not separated.
Instead, build a team of subagents
* A subagent is a focused Claude agent spawned by a parent (orchestrator) to perform one task.
* Each subagent has:
* its own conversation context (so domain chatter doesn't interfere),
* a narrow toolset (principle of least privilege),
* a system prompt that defines its role and constraints.
Typical agent-definition fields
| Field | Meaning | Example |
| - | - | - |
| `name` | Human-friendly label | `Network Configurator` |
| `id` | Unique identifier | `network-specialist` |
| `description` | What the agent is responsible for | `Create VPC, subnets, and route tables` |
| `system_prompt` | Role-setting prompt for expertise and constraints | `You are a network engineer...` |
| `tools` | Exact toolset allowed for the agent | `["Bash", "Read"]` |
Registering subagents
* Register subagents by passing a list of agent definition objects to the SDK client.
* If you start a definition with "Use proactively", Claude will select that specialist automatically when a request matches the description.
Roles for VPC automation
* Network agent: creates the VPC, subnets, route tables, and attaches gateways.
* Security agent: creates security groups, NACLs, policy checks and performs audits.
* Orchestrator (parent): decomposes requests, delegates to subagents via the Task tool, and aggregates results.
Principle of least privilege: lock tools per agent
* Limit each subagent to only the tools necessary for its job.
* Example tool sets:
* Network agent: `["Bash", "Read"]` (run AWS CLI commands and inspect state).
* Security agent: `["Bash", "Read"]` (create and audit security rules).
* Orchestrator (parent): `["Bash", "Read", "Write"]` (coordinate and perform higher-privilege tasks).
* Narrow tool access reduces the blast radius and enforces separation of duties at runtime. Combine this with a precise system prompt for defense in depth: neither the network agent nor the security agent should be able to perform the other's responsibilities, either by prompt or by tools.
Restrict tools to the minimum required for each agent. Combined with a precise system prompt, this reduces risk by enforcing separation of duties.
Order matters: create networking resources (VPC, subnets, route tables) before attaching security controls that depend on resource IDs. Also ensure credentials and IAM roles used by agents follow least privilege rules.
How the team builds a 3-tier VPC
* The network agent runs first to create the underlying resources:
* VPC: 10.0.0.0/16
* Public subnets with a route to an Internet Gateway (for the web tier)
* Private subnets with no direct internet route (for app and DB tiers)
* The security agent runs next to apply policies:
* Create security groups for web, app, and database tiers (default deny, explicit allow).
* Create subnet-edge NACLs to harden ingress/egress at the subnet level.
* Apply rules: web tier allows 80/443 from the internet; app accepts traffic only from the web security group; db accepts traffic only from the app security group.
Run it statefully using a Claude SDK client
* Use a stateful client so conversation context (and resource IDs) persist across turns.
* A typical run has four turns:
Turn 1 — Design
* Orchestrator plans a complete VPC for a three-tier web app and determines necessary resources and dependency order.
Turn 2 — Network
* Orchestrator delegates to the network configurator using the Task tool.
* The network agent runs `Bash` commands (e.g., `aws ec2 create-vpc`) and returns real resource IDs.
Turn 3 — Security
* Orchestrator passes the created resource IDs to the security specialist.
* The security agent creates security groups and NACLs with the correct allow/deny rules for each tier.
Turn 4 — Review
* Orchestrator verifies the final state, checks least privilege across tiers, and returns a consolidated report.
Example CLI-style run
```bash theme={null}
$ python vpc_orchestration.py
Turn 1 · Design Orchestrator plans a 3-tier VPC
Turn 2 · Network ☒ Task network-configurator
☒ Bash aws ec2 create-vpc --cidr-block 10.0.0.0/16
vpc-0a1b2c3d created · 2 public + 4 private subnets
Turn 3 · Security ☒ Task security-specialist
☒ Bash create-security-group → web · app · db
Turn 4 · Review least privilege verified ✓
```
Sample agent definition (JSON)
* Register each subagent as a definition object and supply the `tools` field to enforce least privilege.
```json theme={null}
{
"name": "Network Configurator",
"id": "network-specialist",
"description": "Creates VPC resources: VPC, subnets, route tables, and IGW",
"system_prompt": "You are a network engineer. Only perform network resource creation and return structured resource IDs.",
"tools": ["Bash", "Read"]
}
```
Extend the team
* Add extra specialists (e.g., audit-specialist, iam-manager, terraform-applier) to plug in external tools or cross-check configurations.
* Use the Task tool for delegation so the orchestrator never calls subagents directly — Claude chooses the right specialist automatically based on description.
Benefits summary
| Benefit | Why it matters |
| - | - |
| Reduced blast radius | Each agent has minimal tools and scope, limiting accidental wide-impact changes. |
| Clear ownership | Each domain (network vs security) has its own context and responsibilities. |
| Better debugging | Failures are localized to a specialist instead of a single monolithic agent. |
| Auditability | Structured outputs (resource IDs, commands run) make post-facto audits straightforward. |
Links and references
* [AWS VPC documentation](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html)
* [Principle of Least Privilege (Microsoft)](https://learn.microsoft.com/security/compass/least-privilege)
* Claude/Anthropic general docs: [https://www.anthropic.com/](https://www.anthropic.com/)
What was once one overloaded agent is now a small, safe, well-run team with clear ownership and limited permissions — suitable for production-grade VPC automation.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.