[Design Proposal] Agents Are Not Just Applications — A Model for Managing Digital Workers

[nadheesh]

Problem

AI agents are different from applications — but the platforms we use to run them treat them as if they aren't.

AI agents decide, act, and adapt. They use tools on behalf of people. They spend money — LLM tokens, compute, API calls. They can make mistakes with real consequences. They work alongside humans, sometimes replacing them, sometimes augmenting them. This is fundamentally different from a web service that waits for a request and returns a response.

The industry is in the middle of a shift:

Era	Unit of Work	How You Manage It
Cloud apps (2010s)	Microservice	Deploy, scale, monitor
AI models (2020s)	Model endpoint	Serve, fine-tune, evaluate
AI agents (2026+)	Digital worker	Onboard, assign work, govern, audit, budget

Agent identity is not "an application with some tokens." An application has an endpoint. An agent has a history — what it's done, what it's learned, who it's accountable to, how much it's spent. Its identity grows over time. You don't ask "who owns this API?" or "what did this API learn last month?" — but you absolutely ask those questions about an agent.

Agents can't be shared like APIs. With APIs, you share the deployment — everyone calls the same endpoint, same code, same state. With agents, you can't. Team A needs their GitHub connected with strict merge approval. Team B needs their GitHub with relaxed rules and different context. Everyone wants the same capability, but loaded with their own tools, their own context, their own governance. You share the blueprint, not the running agent.

Organizations adopting agents are asking questions that no app platform was ever designed to answer:

• Who is this agent accountable to? Every agent needs an owner — a human responsible for what it does.
• What is it allowed to do? Agents need scoped permissions, not root access to everything.
• How much can it spend? Without budget controls, a single runaway agent can incur thousands of dollars overnight.
• What did it actually do? Agents make autonomous decisions. Every action needs an audit trail.
• Can I trust it with this task? Some actions need human approval before the agent proceeds.
• Can multiple teams reuse the same capability? There's no way to share the recipe without sharing the kitchen.

Today, our platform cannot answer any of these questions — because it models agents as containers, not as workers. There is no concept of an agent's identity, no owner accountable for its behavior, no budget that spans its work, no way to define what it's allowed to do. Developers build agents as one-off scripts. Teams cannot reuse them. Nobody governs them.

The missing abstraction is the managed digital worker: a capability that sits between a dumb application and a fully autonomous employee — with identity, boundaries, accountability, and a lifecycle managed by the platform.

Application              Agent                    Human Employee
(no autonomy)           (bounded autonomy)        (full autonomy)

Does exactly         Decides how to            Makes independent
what you tell it     accomplish a goal,        decisions, sets
                     within defined            own goals
                     boundaries

No identity          Has identity,             Has identity,
No budget            budget, audit trail       compensation,
No governance        governance controls       HR oversight

This proposal defines what it means to build a platform for managed digital workers — not just a container runtime with an AI label.

---

User Stories

• As an agent developer, I want to publish an agent as a reusable blueprint — defining its capabilities and what owners can configure — so that any team can deploy it for their own purposes without touching my code.

• As an agent owner, I want to onboard an agent into my organization — giving it context about my world, connecting it to my tools, and setting the boundaries of what it's allowed to do — so that it works for my team like a new hire, not a piece of infrastructure.

• As a platform admin, I want to register tools and models, set org-wide policies and budget ceilings — so that every agent deployed in my organization operates within governed boundaries.

---

Existing Solutions

None of the existing platforms fully address the managed digital worker problem. We evaluate them against two questions: (1) Can a developer publish a reusable agent blueprint? (2) Can an owner onboard it — with their own tools, context, and governance — without touching the code?

Agent platforms — how they run agents:

• OpenAI Agents SDK / Assistants API: Treats agents as chat assistants backed by a thread store. No developer/owner separation — the same person who builds it deploys it. No governance model. No way to publish an agent as a reusable capability for other teams to onboard.

• AWS Bedrock AgentCore: Infrastructure-level agent deployment with an Agent Registry (preview 2026) for discovery. The registry catalogs live agents, MCP servers, and tools — but it's a discovery layer for already-running services, not a blueprint catalog. Owner "configuration" is infrastructure configuration (IAM, Lambda), not organizational context. Tools are first-class registry citizens alongside agents.

• Google Cloud Agent Marketplace / Agent Finder: Partners publish Agent Cards (JSON metadata conforming to the A2A protocol) to Google Cloud Marketplace. Customers can add agents to their Gemini Enterprise environment. Closest to a public agent marketplace, but agents run on the partner's infrastructure — the customer connects to a running service, not deploying their own instance.

• Microsoft Agent Store + Copilot Studio: Partners build agents and publish to the Agent Store within Microsoft 365 Copilot. Employees discover and install agents with one click. But the consumer is an end-user, not an owner configuring for a team — there's no blueprint/profile split or governance layer.

• LangGraph Platform (LangChain): Closest technically — framework-agnostic containers, supports webhooks and cron, stateful checkpointing. Has an internal Agent Registry for org-wide discovery. Supports multiple Assistants (configured variants of a deployed graph with different prompts/models/tools). But still developer-centric: no owner configuration layer, no governance model, no identity or accountability built into the platform.

• Paperclip: Introduces the right intuition — agents as persistent, proactive workers that accumulate knowledge over time. Combines heartbeat (cron) and interactive (chat) on the same agent with shared state. But it's a single-tenant product, not a platform where developers publish blueprints for other teams to onboard.

Agent marketplaces — how they publish and share:

• Salesforce AgentExchange: Closest to our model. Partners publish four artifact types: Actions (atomic capabilities), Topics (bundles of actions + instructions), Prompt Templates, and Agent Templates (full agents). A customer installs a template and it becomes their agent — running in their org, with their data, permissions, and identity. Mandatory security review. Native MCP and A2A support. The key difference: locked to the Salesforce platform.

• CrewAI Marketplace: Builders publish crew templates, agent definitions, and tools (separately). Consumer installs, configures env vars and connections. Revenue sharing for enterprise-adopted templates. Tools are independently publishable via a Tool Repository. Close to our model but tied to the CrewAI framework and lacks governance.

• Relevance AI Marketplace: 1,000+ free agents from verified builders. Consumer clones a listing into their project — full modification access after cloning. No-code. But no governance, no identity, no blueprint/profile separation.

Tool registries — how they handle tools:

• Smithery: "Docker Hub for MCP" — 7,000+ MCP servers. Publish tool providers, not agents. Agents consume tools from here. Open community publishing. Under 1 minute to install via CLI.

• Composio: 850+ toolkits, 11,000+ tools. Managed auth (OAuth handled by Composio). Exposed via MCP or direct APIs. Tools are the only artifact — no agent publishing. Handles credential management and API versioning automatically.

Analogous patterns from infrastructure:

• Helm / Artifact Hub: The strongest analogy. A chart (parameterized package) is published to Artifact Hub. An operator installs it with their own values.yaml. The chart is immutable; all customization happens through the values file. Our blueprint/profile split follows the same pattern.

• Terraform Registry: Modules published with input variables. Consumer provides variable values. Module author defines the shape; consumer fills in the parameters. Versioning via semver.

What no platform solves: The full publish → catalog → onboard-as-your-own-worker lifecycle with governance. Salesforce comes closest but is platform-locked. AWS and Google have registries but for discovery of running services, not blueprint deployment. Helm has the right artifact model but for infrastructure, not agents. Our proposal combines Helm's blueprint model with Salesforce's install-as-yours pattern and adds the governance layer that no current agent platform provides.

• Current state in our platform: Agents are containers. Owners can set environment variables at deploy time. There is no blueprint/onboarding separation, no governance model, no shared identity or audit trail tied to the agent as a worker.

---

Proposed Solution

Overview

The solution has two parts that map directly to the two user stories.

For developers — the blueprint model. An agent is published as a reusable blueprint: code, a spec (agent.yaml), and a declaration of what owners can configure. The spec declares the agent's requirements — which tools it needs (registered in the Tool Gateway), what state it uses, what parameters owners can set. Developers build the capability once and publish it to the Agent Catalog — the platform's internal registry of available blueprints.

For owners — the onboarding model. An owner browses the Agent Catalog, picks a blueprint, and creates a deployment — the platform's equivalent of hiring and onboarding. Through the console, the owner configures the agent profile: connects tools from the Tool Gateway, picks a model from the LLM Gateway, sets triggers, provides context, and sets budget limits. The result is a governed, accountable digital worker operating within that team's world — without the owner writing a line of code.

For platform admins — org-wide policies. Platform administrators register tools (API endpoints, MCP servers) in the Tool Gateway, configure model providers in the LLM Gateway, and set org-wide policies: default budget ceilings, governance baselines, and compliance rules. These are configured through the platform console and apply across the organization.

The Agent Catalog connects the two stories:

Developer                     Agent Catalog                      Owner

Code + agent.yaml   push     ┌──────────────┐   browse      Console
─────────────────────────►   │ code-reviewer │ ◄──────────   (discover)
                     build   │ v1.0          │
CI/CD builds image   ─────► │              │   deploy       Onboarding
                             │ Blueprint:   │ ──────────►   flow
                             │  requirements│               (configure
                             │  parameters  │                profile)
                             │  schemas     │
                             │  image: ✓    │               DEPLOYMENT
                             └──────────────┘               (running agent)

The Agent Catalog is an internal blueprint registry — not a public marketplace. Unlike AWS's Agent Registry (which catalogs already-running services) or Google's Agent Finder (which connects to partner-hosted agents), our catalog stores blueprints that aren't running yet — like Helm's Artifact Hub stores charts or Docker Hub stores images. Teams within the organization discover blueprints and deploy them as their own agents with their own identity, tools, and governance.

Key Definitions

Concept	What It Is	Who Defines It
Agent Blueprint	The code — skills, logic, reasoning, tools. What the agent can do. Includes parameter shapes, state requirements, input/output schemas.	Developer writes it
Agent Profile	How the agent operates — triggers, tools, model, state, learning, interface, parameters, governance. What makes it alive as a worker.	Owner configures per deployment, Platform provides defaults and policies

AGENT (instance) = BLUEPRINT (class) + PROFILE

The agent profile is what makes this work technically. Instead of forcing agents into types (API agent, Job agent, Chat agent), the platform defines each agent as blueprint + agent profile. The blueprint is the code — what the agent can do. The agent profile is how it operates, remembers, and learns — when it wakes up, what it remembers, how it improves from its own history, what guardrails apply.

This is necessary because real agents — Devin, Claude Code, Paperclip — don't fit one type. They compose multiple behaviors within the same agent. The agent profile lets an owner activate a cron heartbeat AND a chat interface on the same deployment, with shared state, without any code changes.

┌──────────────────────────────────────────────────────────────┐
│              AGENT = BLUEPRINT + AGENT PROFILE              │
│                                                               │
│  Blueprint: the code — skills, logic, reasoning               │
│                                                               │
│  Agent Profile: how it operates, remembers, and learns        │
│    TRIGGERS ──── chat, cron, webhook, manual, api             │
│      ├── execution: short-lived | long-lived (per trigger)    │
│      └── concurrency: exclusive | per-user | concurrent       │
│    TOOLS ──────── from Tool Gateway (per-action governance)   │
│    MODEL ──────── from LLM Gateway (provider, model, budget)  │
│    STATE ──────── deployment-scoped, user-scoped              │
│    LEARNING ───── hot-path, offline (trace → context graph)   │
│    INTERFACE ──── headless, chat-ui                           │
│    PARAMETERS ─── context config (instructions, settings)     │
│    GOVERNANCE ─── budget, org policies                        │
│                                                               │
│  Blueprint code is the SAME regardless of agent profile.      │
│  Profile properties are ORTHOGONAL — mix and match freely.    │
└──────────────────────────────────────────────────────────────┘

Three configuration levels — each narrows the scope of what the next level can do:

Level	Who	Where	What They Configure
Platform admin	Org-wide admin	Platform console	Register tools in Tool Gateway, register models in LLM Gateway, set budget ceilings, org-wide governance policies
Owner	Team lead / agent owner	Console (deployment)	Connect tools (with per-action approval gates), pick model, set triggers, provide context parameters, set budget, configure learning
Developer	Agent builder	agent.yaml	Blueprint code, required tools and actions, state requirements, parameter shapes, input/output schemas, governance defaults

Platform sets the guardrails. Owner operates within them. Developer builds the capability that both configure.

Key insight: All triggers within a deployment share the same state, identity, and credentials. A trigger is a door into the same room, not a different room. This enables the Paperclip heartbeat+chat pattern natively: one agent, one deployment, two entry points, shared memory.

Design

Agent Profile Properties

Triggers — how invocations arrive

A deployment can have multiple active triggers simultaneously. The agent code receives identical input regardless of which trigger fired. Each trigger carries its own execution and concurrency settings — because the same agent may be short-lived for a chat message but long-lived for a manual deep-analysis run.

Trigger	How It Works	Platform Provides
chat	User sends messages in a session	Session management, streaming, message history, user routing
webhook	External system sends HTTP event	Webhook endpoint, event filtering, payload transformation, retry
cron	Time-based recurring invocation	Scheduler, run history, missed-run handling, timezone support
manual	User runs via UI or API with explicit input	Job queue, input form, progress tracking, artifact storage
api	Synchronous request/response endpoint	Load balancing, auto-scaling, rate limiting, service auth

Execution — per-trigger, not global. A binary choice that determines the execution contract:

Option	Execution Model	Platform Provides
short-lived	Synchronous request → response. Agent is invoked, does work, returns.	Configurable timeout (seconds to minutes). Standard HTTP lifecycle.
long-lived	Async task with its own lifecycle. Agent runs as a managed task that can be monitored, paused, resumed.	Checkpointing, pause/resume, progress reporting, workspace provisioning, mid-run approval gates, run status API.

Concurrency — per-trigger, not global. Controls the request queuing strategy when multiple invocations arrive:

Option	Behavior	When to Use
exclusive	One run at a time. Others queue or are rejected.	Cron heartbeats (prevent overlapping runs), agents that modify shared state unsafely
per-user	One run per user at a time. Different users run concurrently.	Chat triggers (each user gets their own queue, users don't interfere)
concurrent	All invocations run in parallel. Platform scales as needed.	API triggers, high-volume webhook handlers

Example — same agent, different execution and concurrency per trigger:

triggers:
  - type: webhook
    source: github
    event: pull_request.opened
    execution: short-lived
    max_duration: 5m
    concurrency: concurrent
  - type: chat
    session_ttl: 24h
    execution: short-lived
    max_duration: 30s
    concurrency: per-user
  - type: cron
    schedule: "0 9 * * MON"
    execution: short-lived
    concurrency: exclusive
  - type: manual
    execution: long-lived
    max_duration: 2h
    checkpoint:
      interval: 5m
      storage: 10Gi
    concurrency: exclusive

State — what survives between runs

State is defined by scope — who can see it — not by duration (short-term vs long-term). Two independent scopes, either or both can be enabled:

Scope	Who Sees It	Platform Provides	Example
deployment-scoped	All runs, all triggers, all users within this deployment	Key-value store, vector memory, shared across triggers	Heartbeat writes findings → chat users read them
user-scoped	Only runs for a specific user within this deployment	Per-user memory store, conversation history, TTL cleanup	Chat with Alice has separate context from chat with Bob

An agent with neither scope is stateless — each run is independent. An agent with both scopes gets shared knowledge (deployment) AND per-user conversations (user). The Paperclip heartbeat+chat pattern needs exactly this:

Cron heartbeat → writes to deployment-scoped memory (findings)
Chat with Alice → reads deployment-scoped + writes to user-scoped (Alice's conversation)
Chat with Bob   → reads deployment-scoped + writes to user-scoped (Bob's conversation)

State is what creates behavioral "autonomy." A cron-triggered agent with no state is a scheduled script. The same agent with deployment-scoped state is a heartbeat agent — it remembers what it found last time, tracks trends, builds knowledge.

Learning — how the agent improves over time

Learning is how the agent's knowledge grows beyond what the developer coded and the owner configured. Two mechanisms, either or both can be enabled:

Mechanism	How It Works	Platform Provides	Example
hot-path	Agent code writes to memory during a run. The agent decides what's worth remembering.	Memory write API available during execution.	Agent stores "this user prefers concise reviews" after a conversation.
offline	Platform analyzes completed run traces after the fact and extracts structured knowledge into a context graph.	Trace collection, offline analysis pipeline, context graph store.	Platform notices "PRs from author X consistently have SQL injection issues" across 50 runs.

Hot-path learning is agent-driven — the code decides what to remember. Offline learning is platform-driven — the platform mines patterns from execution history that no single run could see.

Context graph: Offline trace analysis produces structured knowledge, not flat key-value memories:

Context Graph (built by platform from traces)
├── Entities: repos, users, tools, APIs the agent has interacted with
├── Patterns: "PRs from this author usually have security issues"
├── Outcomes: "this review approach caught more bugs than that one"
├── Preferences: "this user prefers detailed explanations"
└── Relationships: "repo-A depends on repo-B, changes propagate"

The context graph is scoped the same way as state — deployment-scoped (shared patterns) and user-scoped (per-user preferences). It feeds into the agent's knowledge alongside hot-path memories, but the agent code doesn't need to do anything — the platform populates it automatically.

learning:
  hot_path: true              # agent writes memories during runs
  offline:
    enabled: true             # platform analyzes traces
    context_graph: true       # build structured knowledge graph
    trace_retention: 30d      # how long to keep traces for analysis

Interface — does the platform provide a user-facing surface?

Every agent is an HTTP service with POST /invoke — that's the transport, not the interface. This property is about what user-facing surface the platform provides on top:

Option	Platform Provides
headless	No user-facing UI. Agent is invoked by triggers only. Results go to APIs, databases, downstream systems.
chat-ui	Platform provides a conversational interface — chat widget, message rendering, streaming, user routing.

Multiple interfaces are additive, not exclusive. A Devin-style agent might expose chat-ui (for the human to monitor and give feedback) and headless (for automated webhook triggers).

Tools — what the agent connects to (via Tool Gateway)

The platform's Tool Gateway is where admins register external services — API endpoints, MCP servers, OAuth apps — as named tools. Each registered tool exposes actions that the platform knows about and can govern. A connection is a Tool Gateway concept: a registered instance of a tool with its credentials and endpoint configuration (e.g., team-backend-github is a connection to the github tool with Team Backend's credentials).

The developer declares which tools the agent needs in agent.yaml (requires.tools). The owner connects tool instances (connections) from the Tool Gateway and sets per-action governance (auto-approve, requires-approval, or disabled). The platform validates, injects credentials as env vars, and enforces action governance at runtime.

Actions are not magic strings — they come from the Tool Gateway registration. The platform can validate and enforce because it knows what each action means. The owner never sees vault paths or API keys; they pick tools from a dropdown in the console.

Note: tools that are internal to the agent code (e.g., parse_diff(), custom utility functions) are part of the blueprint — they don't need to be declared in agent.yaml because the platform has nothing to provide or govern for them.

Model — which LLM the agent uses (via LLM Gateway)

The platform's LLM Gateway is where admins register model providers. The owner picks a model from the gateway for each deployment. The platform routes all LLM traffic through the gateway, which handles:

• Model routing (provider, model selection)
• Token tracking and cost attribution
• Budget enforcement (per-deployment spending limits)
• Rate limiting and quota management

The agent code doesn't need to know the provider — it reads AMP_LLM_BASE_URL and MODEL_NAME from env vars, and the gateway handles routing.

Governance — budget and org policies

Governance is what the platform actively enforces at runtime — not just configuration passed through to the agent.

Capability	Who Sets It	How Platform Enforces
Budget	Owner sets limit, platform admin sets ceiling	LLM Gateway tracks token spend, alerts at threshold, hard-stops at limit
Tool action approval	Owner sets per action (from Tool Gateway)	Platform intercepts tool calls, blocks until approved
Allowed actions	Owner enables/disables per tool	Platform rejects calls to disabled actions
Org policies	Platform admin	Applied as defaults/ceilings across all deployments

Entity Model

Organization (platform admin sets org-wide policies via console)
├── Tool Gateway: [GitHub, Slack, Jira, ...]      ← admin registers
├── LLM Gateway: [anthropic, openai, ...]         ← admin registers
│
├── Agent Catalog (blueprint registry — nothing is running here)
│   ├── code-reviewer v1.0    ← developer published
│   ├── support-agent v2.3    ← developer published
│   └── data-analyst v1.1     ← developer published
│
└── Project
    └── Deployment A (owned by Team Alpha)         ← owner deployed code-reviewer
    │   ├── Blueprint: code-reviewer v1.0
    │   ├── Tools: GitHub [read_code✓, review_pr⚠️, merge_pr✗]
    │   ├── Model: claude-sonnet-4-6 (via LLM Gateway)
    │   ├── Triggers: [webhook (concurrent), manual (exclusive)]
    │   ├── Parameters: { review_focus: "security" }
    │   ├── Budget: $50/mo
    │   └── Status: Active
    │
    └── Deployment B (owned by Team Beta)          ← owner deployed same blueprint
        ├── Blueprint: code-reviewer v1.0
        ├── Tools: GitHub [read_code✓, review_pr✓, merge_pr⚠️, file_issue✓]
        ├── Model: gpt-4o (via LLM Gateway)
        ├── Triggers: [cron (exclusive), chat (per-user)]
        │          ↑ ALL triggers share the same state and identity
        ├── Parameters: { review_focus: "general" }
        ├── Budget: $100/mo
        └── Status: Active

Entity	What It Is	Who Owns It
Agent Catalog	Internal blueprint registry. Stores versioned, immutable blueprints — nothing is running here. Like Helm's Artifact Hub for agents.	Platform provides
Agent (Blueprint)	Code + agent.yaml + image. Declares requirements and parameter shapes. Published to the Agent Catalog.	Developer
Deployment	Owner's configured agent profile. Created by deploying a blueprint from the catalog. Triggers, tools, model, parameters, governance. All triggers share state.	Owner
Run	Single invocation from any trigger. Tagged with trigger source.	Platform tracks

Agent Blueprint (agent.yaml)

The blueprint spec is what the developer ships alongside agent code. It declares what the agent can do and what owners need to configure — but it does not configure the agent profile itself. That's the owner's job.

apiVersion: amp/v1
kind: AgentSpec

metadata:
  name: code-reviewer
  version: "1.0"
  description: "AI-powered code review agent"
  tags: ["coding", "review", "security"]

entrypoint:
  handler: "main.run"        # SDK mode: platform wraps into HTTP server
  # type: http               # BYO mode: agent is already an HTTP server
  # port: 8080
  # path: /invoke

# What the agent needs from the platform
requires:
  tools:
    - name: github             # must be registered in Tool Gateway
      actions: [read_code, review_pr, merge_pr, file_issue]
      required: true
    - name: slack
      actions: [send_message]
      required: false
  state:
    deployment_scoped: true    # agent code uses shared memory
    user_scoped: true          # agent code uses per-user memory
  # platform-managed: platform provides memory APIs (key-value, vector store)
  # self-managed: agent brings its own storage (e.g., external DB) — platform only provides identity context
  memory: platform-managed

# Parameters — context config the owner provides at deployment
# All become environment variables in the container
parameters:
  - name: instructions
    type: text
    source: file
    file: instructions.md
    owner_appendable: true
    env_var: AGENT_INSTRUCTIONS
    description: "Behavioral guidelines — domain rules, tone, standards"

  - name: review_focus
    type: string
    default: "general"
    options: ["security", "performance", "style", "general"]
    env_var: REVIEW_FOCUS

# Developer's suggested governance defaults — owner can override
# Namespaced by tool to avoid ambiguity (tool.action)
governance:
  defaults:
    github.merge_pr: requires_approval
    github.file_issue: auto_approve
    github.read_code: auto_approve
    github.review_pr: auto_approve
    slack.send_message: auto_approve

# Input/output schemas — triggers map event data to this schema
input:
  type: object
  properties:
    text: { type: string }   # chat and manual triggers
    diff: { type: string }   # webhook and manual triggers
    pr_url: { type: string }
    author: { type: string }

output:
  type: object
  properties:
    comments: { type: array }
    summary: { type: string }
    approval:
      type: string
      enum: [approve, request_changes, comment]

resources:
  memory: "512Mi"
  cpu: "0.5"

The developer declares what the agent needs (requires.tools, requires.state), what owners can configure (parameters), and suggested governance defaults for tool actions. They do not decide triggers, execution mode, concurrency, interface, learning, model, or budget — those are the owner's decisions within platform policies.

Owner Deployment Config

The owner takes a blueprint and creates a deployment through the console — configuring the agent profile for their team's needs. This is the onboarding step: connecting tools, picking a model, providing context, setting boundaries.

deployment:
  agent: code-reviewer
  version: "1.0"
  environment: prod
  owner: team-backend

  # Tools — connect from Tool Gateway, set per-action governance
  # Developer suggested: github.merge_pr=requires_approval, github.file_issue=auto_approve
  # Owner overrides: file_issue=disabled (don't want agent filing issues),
  #                  review_pr=requires_approval (extra caution for this team)
  tools:
    - name: github
      connection: team-backend-github      # registered in Tool Gateway
      actions:
        read_code: auto_approve
        review_pr: requires_approval       # ← owner overrides developer's auto_approve
        merge_pr: requires_approval        # ← keeps developer's default
        file_issue: disabled               # ← owner disables this action entirely
    - name: slack
      connection: team-backend-slack
      actions:
        send_message: auto_approve

  # Model — pick from LLM Gateway
  model:
    provider: anthropic
    model: claude-sonnet-4-6

  # Triggers — when the agent runs
  triggers:
    - type: webhook
      source: github
      event: pull_request.opened
      execution: short-lived
      max_duration: 5m
      concurrency: concurrent
      input_mapping:
        diff: "$.pull_request.diff_url"
        pr_url: "$.pull_request.html_url"
        author: "$.pull_request.user.login"
    - type: cron
      schedule: "0 9 * * MON"
      execution: short-lived
      concurrency: exclusive
    - type: chat
      session_ttl: 24h
      execution: short-lived
      max_duration: 30s
      concurrency: per-user
    - type: manual
      execution: long-lived
      max_duration: 2h
      checkpoint:
        interval: 5m
        storage: 10Gi
      concurrency: exclusive

  interface: [headless, chat-ui]

  learning:
    hot_path: true
    offline:
      enabled: true
      context_graph: true
      trace_retention: 30d

  # Parameters — fill in the shapes from the blueprint
  parameters:
    review_focus: "security"
    instructions_append: "Flag SQL injection. Reject eval()."

  # Budget
  budget:
    monthly_limit: 50.00
    alert_threshold: 0.8

The developer builds the what and suggests governance defaults. The owner decides the how, when, and within what limits — overriding defaults where their team needs different rules, all within guardrails set by the platform admin.

Console experience — the owner never writes YAML. The console renders the blueprint's requirements as a guided onboarding flow:

Deploy "code-reviewer" v1.0 for team-backend
──────────────────────────────────────────

Tools (from Tool Gateway):
  ☑ GitHub (required)       → [team-backend-github ▾]
    Actions:
      ☑ read_code            [auto-approve]
      ☑ review_pr            [requires approval ⚠️]    ← developer suggested auto
      ☑ merge_pr             [requires approval ⚠️]    ← developer suggested this
      ☐ file_issue           [disabled]                ← developer suggested auto
  ☑ Slack (optional)        → [team-backend-slack ▾]
    Actions:
      ☑ send_message         [auto-approve]

Model (from LLM Gateway):
  [anthropic / claude-sonnet-4-6 ▾]

Parameters:
  Review focus: [security ▾]
  Instructions: [Append: "Flag SQL injection. Reject eval()."]

Triggers:
  + Webhook (GitHub PR opened)  [short-lived, concurrent]
  + Chat                        [short-lived, per-user]
  + Cron (Mon 9am)              [short-lived, exclusive]
  + Manual                      [long-lived, exclusive]

Budget: [$50/month] Alert at [80%]

File-sourced parameters: Any parameter can have source: file, loading the content of a file shipped with the agent. This is how behavioral instructions, prompt templates, or configuration documents reach the agent — as env vars that the developer's code explicitly reads and places in LLM context. The platform never injects file content into LLM calls directly.

Why not proxy injection for instructions?

1. Requires ALL LLM traffic through the proxy — can't guarantee for BYO agents
2. Multi-agent/multi-purpose LLM calls get wrong instructions injected
3. Accuracy degradation from owner-appended freeform text in system prompts

Platform-Injected Environment

The platform injects everything the agent needs as env vars — tool credentials, LLM gateway endpoint, identity, and platform APIs. The agent code never manages credentials or knows about vault paths.

# LLM Gateway — owner's model choice routed through platform
# Platform-agnostic names. Agents using OpenAI-compatible SDKs can alias:
#   OPENAI_BASE_URL=$AMP_LLM_BASE_URL  OPENAI_API_KEY=$AMP_LLM_API_KEY
AMP_LLM_BASE_URL=https://llm-gateway.platform.internal/v1
AMP_LLM_API_KEY=<platform-managed-key>
MODEL_NAME=<owner-configured>

# Tool connections — injected from Tool Gateway
GITHUB_TOKEN=<from-tool-gateway-connection>
SLACK_WEBHOOK_URL=<from-tool-gateway-connection>

# Agent identity (auto-provisioned)
AMP_AGENT_ID=<id>
AMP_DEPLOYMENT_ID=<id>
AMP_RUN_ID=<id>
AMP_TRIGGER_TYPE=<webhook|cron|manual|chat>

# Platform APIs
AMP_MEMORY_API_URL=https://memory.platform.internal
AMP_API_KEY=<scoped-key>

LLM Gateway routes all LLM traffic, enforces the deployment's budget, and tracks token usage per run.

Agent compliance levels — how well the agent code cooperates with the gateway (this is about developer discipline, not platform configuration):

Level	Agent Code Does	Platform Controls
Full	Reads AMP_LLM_BASE_URL, AMP_LLM_API_KEY, MODEL_NAME from env	Model routing, budget, tracking — full platform control
Partial	Reads API key from env, hardcodes model name	API routing, budget enforcement. Model change requires code change.
Minimal	Hardcodes everything	Resource limits only — platform has no visibility into LLM usage

Tool Gateway manages tool connections — credentials, access validation, and action-level governance. When an agent calls a tool action, the platform can intercept and enforce approval gates before the call proceeds.

State in Practice — Code Example

The heartbeat+chat pattern combines both state scopes in one deployment:

def run(input, context):
    shared = recall_deployment_memory()     # deployment-scoped
    user_history = recall_user_memory()     # user-scoped (empty for cron)

    if input.get("text"):
        # Chat trigger — answer from shared knowledge + user context
        response = answer(input["text"], shared, user_history)
        store_user_memory(input["text"], response)
        return response
    else:
        # Cron trigger — heartbeat, update shared knowledge
        findings = scan_jira_and_slack()
        store_deployment_memory("latest_scan", findings)
        return {"status": "heartbeat complete"}

Same deployment. Same code. Cron writes to shared memory. Chat reads shared + writes per-user. When offline learning is enabled, the platform also builds a context graph from completed run traces — the agent queries this alongside hot-path memories without extracting patterns itself.

System Architecture

┌──────────────────────────────────────────────────────────────┐
│                  PLATFORM SERVICES                            │
│                                                               │
│  ┌────────────────┐                                           │
│  │ Agent Catalog   │ blueprints (versioned, not running)      │
│  │ (registry)      │───────────────────────────┐              │
│  └────────────────┘                            │ deploy       │
│                                               ▼               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐       │
│  │ Webhook  │  │ Cron     │  │ Chat     │  │ Manual │       │
│  │ Router   │  │ Scheduler│  │ Gateway  │  │ API    │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └───┬────┘       │
│       └─────────────┴─────────────┴─────────────┘            │
│                             ▼                                 │
│                  ┌──────────────────┐                         │
│                  │ Trigger          │  Maps event → input     │
│                  │ Controller       │  schema via owner config │
│                  └────────┬─────────┘                         │
│                           │                                   │
│  ┌────────────────┐       │       ┌────────────────┐         │
│  │ Tool Gateway   │       │       │ LLM Gateway    │         │
│  │ ─ connections  │       │       │ ─ model routing│         │
│  │ ─ action gov.  │◄──── │ ────►│ ─ budget/track │         │
│  │ ─ credentials  │       │       │ ─ rate limits  │         │
│  └────────────────┘       │       └────────────────┘         │
└───────────────────────────┼───────────────────────────────────┘
                            │ HTTP
                            ▼
               ┌────────────────────────────────┐
               │ Agent Pod                       │
               │ POST /invoke                    │
               │ { input, context }              │
               │                                 │
               │ ← Tool calls go through         │
               │   Tool Gateway (action gov.)    │
               │ ← LLM calls go through          │
               │   LLM Gateway (budget/routing)  │
               └────────────────────────────────┘

Agent Lifecycle

BLUEPRINT LIFECYCLE (developer)

┌─────────┐    push     ┌─────────┐   publish    ┌──────────┐
│ Created │ ──────────► │ Built   │ ───────────► │ In       │
│ (spec   │             │ (image  │              │ Catalog  │
│ written)│             │ ready)  │              │ (version-│
└─────────┘             └─────────┘              │ ed)      │
                                                  └──────────┘

DEPLOYMENT LIFECYCLE (owner)

                            ┌──────────┐
              owner picks   │ In       │
              from catalog  │ Catalog  │
                            └────┬─────┘
                                 │ deploy (configure profile)
                                 ▼
                            ┌─────────┐
                     ┌─────►│ Active  │◄────┐
                     │      │ (runs,  │     │ update
                     │      │ triggers│     │ (new blueprint version,
                     │      │ wired)  │─────┘  profile stays, rollback
                     │      └────┬────┘        available)
                     │  pause │  │ resume
                     │  (manual,  │
                     │  budget,   │
                     │  errors)   │
                     │      ┌────▼────┐
                     │      │ Paused  │
                     │      └────┬────┘
                     │           │ terminate
                     │      ┌────▼──────┐
                     │      │ Terminated│
                     │      └───────────┘

Data Model Changes

Current	Proposed	Changes
agents table	Agent (blueprint: code + agent.yaml spec)	Add: spec column (JSONB) — requirements, parameter shapes, schemas
deployments table	Deployment (owner's configured agent profile)	Add: triggers (JSONB), learning (JSONB), interface (JSONB), parameters (JSONB), budget (JSONB)
agent_configurations	Model config per deployment (via LLM Gateway)	Extend to link to deployment + LLM Gateway
— (new)	deployment_tools table	deployment_id, tool_name, connection_id, action_governance (JSONB)
— (new)	trigger_config table	Multiple triggers per deployment, with per-trigger execution/concurrency
— (new)	agent_runs table	run_id, deployment_id, trigger_type, user_id, input, output, cost, duration, status
— (new)	deployment_budgets table	deployment_id, monthly_limit, current_spend, status
— (new)	agent_memory table	deployment_id, user_id (null for deployment-scoped), key, value, created_at

Out of Scope

• Agent-to-agent communication and multi-agent orchestration
• Computer-use (browser/RPA) agents
• Public agent marketplace (Agent Catalog is internal/org-scoped only in this proposal)
• Fine-tuning or model training
• Vector database selection and management
• Authentication/identity federation between agents and external systems (covered in separate agent-identity proposal)

---

Alternatives Considered

Approach	Trade-offs	Why Not
Type-based model (API/Job/Chat/Autonomous agent types)	Simple mental model initially.	Breaks the blueprint model — if an agent's type is fixed, an owner can't change how it's activated without a new deployment. Real agents like Claude Code and Devin span multiple types. Typing prevents the composition that makes blueprints reusable.
Separate deployments per trigger	Simpler per-deployment infrastructure; no shared-state coordination.	Destroys the onboarding model — an owner who wants heartbeat + chat has to maintain two deployments of the same agent with separate configs, credentials, and budgets. State cannot be shared. The agent has two identities instead of one.
Proxy injection for behavioral instructions	Platform controls how owner instructions reach the LLM; cleaner owner UX.	Requires ALL LLM traffic through the proxy — can't guarantee for BYO agents. Breaks when an agent calls multiple LLMs for different purposes. Accuracy degrades from owner-appended freeform text injected blindly. The developer must remain in control of what reaches the LLM context.
Sidecar services for triggers	Better isolation, co-scaled with agent pod, same lifecycle as Dapr/Envoy.	No precedent in the AI agent space yet. Shared platform services are simpler to start; sidecar migration is straightforward later if needed.
First-class agent.md concept	Dedicated UI editor, versioning, always-present field for behavioral instructions.	Not every agent uses an LLM — adding a concept tax on all blueprints undermines the generality of the model. File-sourced parameters achieve the same outcome without special-casing one parameter type.
Flat parameters with categories (context/integrations/governance)	Simpler developer spec — everything is just a parameter with a category label.	The platform does fundamentally different things with tools (action-level governance via Tool Gateway), models (routing via LLM Gateway), and budget (active enforcement). Treating them as flat parameters hides the fact that the platform has real infrastructure (gateways) backing each concern. Categories without platform enforcement are just labels.
Registry of running agents (AWS Agent Registry model)	Simpler — just catalog what's already deployed. No blueprint lifecycle.	Doesn't solve the onboarding problem. If the agent is already running, the owner can't configure it for their team. Different teams deploying the same agent with different tools, triggers, and governance requires the blueprint → deploy-as-yours pattern, not a phonebook of live endpoints.

---

Open Questions

• Input mapping language: JSONPath (proposed) vs JMESPath vs custom DSL for webhook-to-input schema transformation?
• Profile validation: Should the platform warn or block unusual combinations (e.g., stateless agent with long-lived trigger, or chat trigger with exclusive concurrency)? Or treat all combinations as valid?
• Memory storage: Existing Postgres vs dedicated store (Redis for TTL on user-scoped, vector DB for semantic retrieval on deployment-scoped)?
• Budget granularity: Per-deployment only, or also per-trigger, per-user, per-run limits?
• BYO agent compatibility: How do we validate that a BYO HTTP container (partial/minimal compliance) correctly implements the invoke contract?
• Cross-trigger state consistency: When cron and chat triggers write to deployment-scoped memory concurrently, what's the conflict resolution strategy — locking, last-write-wins, or event sourcing?
• SDK language support: Python first. What's the second? Go (matches backend) or TypeScript (matches most agent framework ecosystems)?
• Tool action governance enforcement: How does the platform intercept tool calls at runtime — proxy layer, SDK hooks, or sidecar? What's the latency cost of approval gates?
• Tool Gateway action discovery: How does the developer discover available actions for a tool when writing agent.yaml? CLI tool, API, or console?
• Agent Catalog trust model: What review/approval process is needed before a blueprint is visible in the catalog? Salesforce mandates security review. Do we need something similar?
• Agent Catalog scope: Org-scoped only for now. When should we support cross-org sharing (public catalog)? What changes in the trust model?

---

Milestones

Phase	Scope	Target
1	Foundation: agent.yaml parser + validator. Agent Catalog (publish, version, browse blueprints). Parameter injection via env vars. File-sourced parameters. Manual trigger. Run tracking. Tool Gateway integration (connect tools, inject credentials). LLM Gateway integration (model routing, basic cost tracking).	Milestone 1
2	Triggers: Webhook trigger (GitHub, generic). Cron/scheduled trigger. Trigger-to-input mapping engine. Chat trigger with session management. Multiple active triggers per deployment with per-trigger execution/concurrency.	Milestone 2
3	State: Deployment-scoped memory (shared key-value + vector store). User-scoped memory (per-user conversation history, preferences). Platform SDK memory methods.	Milestone 3
4	Governance: Tool action governance (per-action approval gates via Tool Gateway). Per-deployment budget enforcement (soft alert + hard stop via LLM Gateway). Full audit trail.	Milestone 4
5	Learning: Trace collection and retention. Offline trace analysis pipeline. Context graph generation (deployment-scoped + user-scoped). Context graph query API for agents.	Milestone 5
6	Advanced: Long-lived execution support (checkpointing, pause/resume, progress reporting). Public Agent Catalog (cross-org sharing). A2A protocol support (agent discovery).	Milestone 6

Dependencies:

• Tool Gateway (exists — needs action-level governance and per-deployment connection management)
• LLM Gateway (exists — needs per-deployment routing and budget enforcement)
• Agent identity and credential model (separate proposal — required before tool connections in Phase 1)
• Container build pipeline (exists — needs agent.yaml spec parsing added)

---

Appendix A: Externally Hosted Agents

The blueprint + profile model assumes the platform can enforce the profile — inject credentials, intercept tool calls, route LLM traffic, enforce budget. For platform-hosted agents this is straightforward: the platform controls the runtime.

But what about externally hosted agents — agents running on someone else's infrastructure?

The Challenge

An externally hosted agent is someone else's container, running somewhere else. The platform controls nothing about its runtime. So how do you enforce a profile on something you don't run?

The Answer: Gateway-Centric Enforcement

The platform doesn't need to control the runtime — it needs to control the doors. The profile is enforced at the gateways, not at the agent.

The key mechanism: credentials never leave the gateways. An externally hosted agent receives a gateway-scoped token, not raw API keys. Every tool call and every LLM call must go through the platform's gateways — because that's the only place the credentials work.

Profile Property	How It's Enforced	Works for External Agents?
Triggers	Platform sends HTTP to the agent's endpoint	Yes — platform controls when to invoke
Tools	Credentials only work through Tool Gateway	Yes — gateway is the chokepoint
Model / LLM	API keys only work through LLM Gateway	Yes — gateway routes and tracks
Budget	Token spend tracked at LLM Gateway	Yes — gateway counts, not the agent
Governance (approval gates)	Tool Gateway intercepts and blocks	Yes — call doesn't proceed without gateway
State	Agent calls platform Memory API	Yes — platform controls the API
Identity	Platform issues scoped tokens	Yes — token only works through gateways
Audit trail	Logged at gateway on every call	Yes — gateways see everything

┌──────────────────────────────────────────────────────┐
│                    PLATFORM                           │
│                                                       │
│  ┌────────────────┐           ┌────────────────┐     │
│  │ Tool Gateway   │           │ LLM Gateway    │     │
│  │ ─ credentials  │           │ ─ API keys     │     │
│  │ ─ action gov.  │           │ ─ budget       │     │
│  │ ─ audit        │           │ ─ audit        │     │
│  └───────▲────────┘           └───────▲────────┘     │
│          │                            │               │
└──────────┼────────────────────────────┼───────────────┘
           │ tool calls                 │ LLM calls
           │ (gateway-scoped token)     │ (gateway-scoped token)
           │                            │
┌──────────┴────────────────────────────┴───────────────┐
│                                                       │
│              External Agent                           │
│              (runs anywhere)                          │
│                                                       │
│  Has: gateway-scoped token, Memory API URL            │
│  Does NOT have: raw API keys, direct tool access      │
│                                                       │
└───────────────────────────────────────────────────────┘

An externally hosted agent and a platform-hosted agent go through the exact same gateways — same governance, same budget enforcement, same audit trail. The profile works identically in both cases.

What You Lose

Agents that bypass the gateways entirely — hardcoding their own API keys and calling tools directly (the minimal compliance level). But that's a deliberate trade-off: if you want platform governance, you go through the gateway. If you don't, the platform has no visibility, and the owner is told exactly that.

This is the same trade-off Kubernetes makes with sidecar proxies — a pod can bypass the service mesh, but then it loses observability, mTLS, and traffic policies. The platform makes the governed path easy and the ungoverned path visible.

[musaabhasan]

The “digital worker” framing is useful because it pushes agent management beyond deployment metadata. I would turn that into a lifecycle object with explicit state transitions.

A practical lifecycle could be:

• Proposed: business owner, intended work, risk tier, data classes, and expected autonomy level.
• Approved: policy pack, tool catalog, budget, escalation path, and evaluation baseline.
• Active: runtime identity, delegated authority, current memory scope, cost telemetry, and incident hooks.
• Constrained: temporary limits after policy drift, abnormal cost, unsafe tool use, or evaluation regression.
• Suspended: credentials revoked, tools disabled, memory frozen, and evidence retained.
• Retired: data retention decision, dependency removal, audit archive, and final owner sign-off.

The key difference from managing applications is that the agent should carry both operational state and accountability state. A service can be healthy while an agent is still unacceptable because its tool use, memory, cost, or decision rationale drifted outside its approved purpose.