The Meta-Agent — Governance Through Conversation

The meta-agent is Powerloom's AI-native admin interface. An Opus-powered agent that sits inside the control plane and provisions governed agent fleets on your behalf — from a plain-English conversation.

Everything it does, you could do with the CLI or the API. The meta-agent does it in 60 seconds, in dependency order, fully governed, fully audited. You talk. It provisions.

---

What It Is

The meta-agent is a Claude Managed Agent (CMA) running on Opus. Its single MCP server wraps the Powerloom REST API — 11 tools that cover reading, creating, and wiring resources across your organization.

It's not a service account. It's not a backdoor. Every action the meta-agent takes is gated by your RBAC permissions. If you can't create an agent in /acme/production with your own credentials, the meta-agent can't either. It's a delegate, not an escalation path.

---

How It Works

You send a prompt ↓ Meta-agent receives it via CMA session ↓ Meta-agent calls Powerloom API tools (list, create, attach) ↓ Each tool call mints a 5-minute JWT scoped to YOUR identity ↓ API enforces YOUR RBAC on every call ↓ Resources are created, wired, and recorded in the audit trail ↓ Meta-agent summarizes what it did

The session-delegated JWT is the key mechanism. When the meta-agent calls a tool, the MCP handler requests a short-lived token from the control plane, bound to the CMA session you started. That token carries your user ID, your organization, and your permissions. The API doesn't know or care that the request came from the meta-agent — it evaluates RBAC against your identity.

5-minute token TTL. Re-fetched on every tool call. No standing privilege.

---

What It Can Do

The meta-agent has 11 tools. Five read the current state. Two look up individual resources. Four create and wire things.

Read tools

Lookup tools

Mutation tools

That's the full surface. The meta-agent can't modify approval policies, can't access other organizations, can't touch the super-admin console, and can't do anything the 11 tools don't cover. The boundary is explicit.

---

Using the Meta-Agent

Starting a session

Invoke the meta-agent the same way you'd invoke any agent — via the API or the console.

From the console: Navigate to the meta-agent in your Agents list and open a session. Type your request.

From the API:

curl -X POST https://api.powerloom.org/agents/$META_AGENT_ID/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "prompt": "Set up a code review agent for the engineering team.",
    "mode": "fire_and_forget"
  }'

Connect to the returned WebSocket URL to stream the conversation.

How to talk to it

The meta-agent is an IT operator co-pilot. It works best when you state what you want and let it figure out the dependency order.

Be specific about what you need:

"Create a PostgreSQL analysis agent for the platform team. It should use the pg-analytics MCP server and the sql-review skill. Owner is admin@acme.com."

The meta-agent will:

1. Look up the user by email to get their principal ID
2. Look up the OU for the platform team
3. Check that the MCP server and skill exist
4. Create the agent
5. Attach the skill
6. Attach the MCP server
7. Mint the credential
8. Report back with the agent ID

Be clear about scope when it matters:

"Provision this in /acme/engineering/platform, not the root OU."

The meta-agent respects OU paths. If you don't specify, it'll ask.

Ask it to check before acting:

"What agents and MCP servers already exist in the engineering OU?"

It'll call the read tools and give you an inventory before creating anything.

What a session looks like

Here's a real interaction pattern:

You:

"Set up a scoped sales-prospecting agent for Emma on the sales team with Apollo and Gmail access."

Meta-agent:

Let me check the current state.

[calls list_ous] — Found /acme/sales [calls describe_user with emma@acme.com] — Emma is in /acme/sales, principal ID e5f6... [calls list_mcp_servers] — Found apollo-mcp and gmail-mcp in /acme/sales [calls list_skills] — Found web-search skill

I'll create the agent in /acme/sales owned by Emma, then wire the MCP servers and mint credentials.

[calls create_agent] — Agent sales-prospector created, ID a1b2... [calls attach_mcp_server_to_agent × 2] — Apollo and Gmail attached [calls attach_skill_to_agent] — web-search attached [calls create_credential × 2] — Bearer tokens minted for both MCP servers

Done. Agent sales-prospector created in /acme/sales:

• Model: claude-sonnet-4-6
• Owner: emma@acme.com
• MCP servers: apollo-mcp, gmail-mcp
• Skills: web-search
• Credentials: minted

The reconciler will push this to CMA within a few seconds. You can invoke it at POST /agents/a1b2.../invoke.

Every tool call in that sequence is RBAC-checked against your identity, executed through your permissions, and recorded in the audit trail.

---

When It Can't Help

The meta-agent surfaces errors directly. If something fails, you see the raw error — no sugar-coating.

Permission denied:

API returned 403: insufficient permissions. You need agent:create on /acme/production to create an agent there. Ask an OrgAdmin to grant a binding, or create the agent in an OU where you have access.

Approval required:

If an approval policy matches the mutation, the meta-agent gets a 202 instead of a 201. It'll tell you:

Agent creation in /acme/production requires approval. Request submitted (ID: req_c3d4...). Your OrgAdmin will see it in the /approvals inbox. The agent will be created once approved.

The meta-agent can't approve its own requests. The approval gate applies regardless of whether the mutation came from a human, the CLI, or the meta-agent.

Resource not found:

No user found with email jane@typo.com. Check the email address and try again.

Reconciler not finished:

Agent created but cma_agent_id is null — the reconciler hasn't pushed it to Anthropic yet. Wait a few seconds and invoke. If it persists, check sync state for errors.

---

Security Model

The meta-agent's security posture rests on three guarantees:

No privilege escalation

The session-delegated JWT carries your identity. The API evaluates RBAC against your user, not against the meta-agent. A prompt injection that tries to escalate privileges hits the same RBAC wall as a malicious API call — the token's sub claim can't be changed by the agent.

No standing access

Tokens are minted per tool call with a 5-minute TTL. There's no long-lived service credential. If the session ends, the tokens expire. If you revoke your own access, the next tool call fails.

Full audit trail

Every mutation the meta-agent makes writes to the control_plane_audit table — append-only, SHA-256 hash-chained, tamper-evident. Each entry carries the delegated_from_session field linking it to the CMA session you started. The audit chain doesn't distinguish between human-initiated and meta-agent-initiated actions — both are first-class entries, both traceable to the authenticated admin.

---

Setup

The meta-agent is bootstrapped once per organization. Your Powerloom admin runs the bootstrap script, which:

1. Deploys the powerloom_meta MCP server (shared fleet, sub-30s)
2. Creates the meta-agent (Opus-powered, user kind, owned by the bootstrapping admin)
3. Attaches the MCP server to the agent
4. Mints the credential

# Local development
docker compose exec api python /app/scratch/bootstrap_meta_agent.py \
  --admin-email admin@dev.local \
  --ou-path /dev-org/engineering

# Production
python scratch/bootstrap_meta_agent.py \
  --api https://api.powerloom.org \
  --admin-email admin@acme.com \
  --admin-token "$JWT" \
  --ou-path /acme/platform

The script is idempotent. Running it twice doesn't create duplicates.

Configuration options

After bootstrap, the meta-agent appears in your Agents list and can be invoked by any user with agent:invoke permission on its OU.

---

Best Practices

State your goal, not the steps. "Set up a code review agent for engineering" is better than "First list the OUs, then find the user, then create the agent..." The meta-agent knows the dependency order.

Name the OU when it matters. If your organization has multiple teams, specify where the agent should live. The meta-agent will ask if you don't, but being explicit saves a round trip.

Check before you create. Ask "What agents exist in engineering?" before creating a new one. The meta-agent checks for existing resources, but you'll have better context about whether something should be reused or replaced.

Use it for provisioning, not troubleshooting. The meta-agent is optimized for creating and wiring resources. For debugging reconciler issues, checking sync state, or diagnosing session failures, the CLI and API give you more direct access.

Trust the error messages. When the meta-agent hits a wall — permission denied, approval required, resource not found — it surfaces the raw API error. The error message is the diagnosis. Act on it directly.