Prompt Management

Prompt Management gives you control over the system prompts that drive Bold Penguin AI agents. Each tenant maintains its own versioned prompt library, independent of other tenants. You can draft new prompts, activate a specific version, roll back to a previous one, and audit every change.

When an agent is invoked, the system resolves its system prompt in this order:

1. The tenant's active prompt version (if one exists)
2. The global default prompt (managed by Bold Penguin)

All prompt endpoints are under the /agentic-flow-gateway/prompts base path and require an authenticated session cookie.

Authentication

All endpoints require a valid session cookie:

Cookie: auth-alpha=<jwt-token>

The cookie is validated against the BP Auth service. Requests without a valid cookie receive a 401 response. Your tenant_id is derived from your session — all reads and writes are automatically scoped to your tenant.

Supported Agents

Prompts can be managed for any of the following agents:

Agent Name	Description
main_agent	Primary conversational agent
intake_agent	Business intake and enrichment
critique_agent	Data quality review
mkt_intel_agent	Market intelligence
mqs_agent	Main Question Set agent
cqs_agent	Carrier Question Set agent
quote_agent	Quote retrieval
planner_agent	Workflow planning
carrier_preference_ranking_agent	Carrier preference ranking

Prompt Versioning

Prompts use a MAJOR.MINOR semantic versioning scheme (e.g., 1.0, 1.1, 2.0). The first version created for an agent is always 1.0.

When creating a new version, specify a bump type:

Bump	Example	When to use
minor	1.0 → 1.1	Iterative refinements — tone, phrasing, additional instructions
major	1.1 → 2.0	Significant restructuring or a new behavioral direction

Only one version can be active per agent at a time. All other versions are drafts. Activating a version immediately takes effect for all agent invocations for your tenant.

API Reference

List Active Prompts

Returns the currently active prompt for every agent that has a tenant-scoped version.

GET /agentic-flow-gateway/prompts

Response:

{
  "prompts": [
    {
      "agent_name": "main_agent",
      "tenant_id": "acme-inc",
      "version": "2.1",
      "is_active": true,
      "prompt_text": "You are an expert insurance agent...",
      "notes": "Improved context handling",
      "created_at": "2025-06-15T10:30:00+00:00",
      "updated_at": "2025-07-12T14:22:00+00:00",
      "created_by": "alice@example.com",
      "updated_by": "bob@example.com"
    }
  ]
}

---

Get Active Prompt

Returns the active prompt for a specific agent. Falls back to the global default if no tenant-scoped version is active. The source field indicates which layer resolved the prompt.

GET /agentic-flow-gateway/prompts/{agent_name}

Response:

{
  "prompt": {
    "agent_name": "main_agent",
    "tenant_id": "acme-inc",
    "version": "2.1",
    "is_active": true,
    "prompt_text": "You are an expert insurance agent...",
    "notes": "Improved context handling",
    "created_at": "2025-06-15T10:30:00+00:00",
    "updated_at": "2025-07-12T14:22:00+00:00",
    "created_by": "alice@example.com",
    "updated_by": "bob@example.com"
  },
  "source": "tenant_prompt"
}

source values:

Value	Meaning
tenant_prompt	Returned the tenant's active version
file_fallback	No tenant version is active; returned the global default

---

List Versions

Returns all versions (active and draft) for an agent.

GET /agentic-flow-gateway/prompts/{agent_name}/versions

Response:

{
  "agent_name": "main_agent",
  "tenant_id": "acme-inc",
  "versions": [
    {
      "agent_name": "main_agent",
      "tenant_id": "acme-inc",
      "version": "2.1",
      "is_active": true,
      "prompt_text": "...",
      "notes": "Improved context handling",
      "created_at": "2025-07-01T09:00:00+00:00",
      "updated_at": "2025-07-12T14:22:00+00:00",
      "created_by": "alice@example.com",
      "updated_by": "bob@example.com"
    },
    {
      "agent_name": "main_agent",
      "tenant_id": "acme-inc",
      "version": "2.0",
      "is_active": false,
      "prompt_text": "...",
      "notes": "Initial v2 rewrite",
      "created_at": "2025-06-15T10:30:00+00:00",
      "updated_at": "2025-06-15T10:30:00+00:00",
      "created_by": "alice@example.com",
      "updated_by": "alice@example.com"
    }
  ]
}

---

Get Specific Version

Returns a single version by number.

GET /agentic-flow-gateway/prompts/{agent_name}/versions/{version}

Example:

curl https://<host>/agentic-flow-gateway/prompts/main_agent/versions/1.0 \
  -b "auth-alpha=<your-session-token>"

---

Create Initial Prompt

Creates the first prompt version (1.0) for an agent. Returns an error if a version already exists.

POST /agentic-flow-gateway/prompts/{agent_name}

Request body:

Field	Type	Required	Description
prompt_text	string	Yes	The system prompt text
notes	string	No	Change notes or rationale
activate	boolean	No	If true, immediately activate this version. Default: false

Example:

curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent \
  -H "Content-Type: application/json" \
  -b "auth-alpha=<your-session-token>" \
  -d '{
    "prompt_text": "You are an expert commercial insurance agent...",
    "notes": "Initial prompt for main agent",
    "activate": true
  }'

---

Create New Version

Creates a new major or minor version, derived from the current latest version.

POST /agentic-flow-gateway/prompts/{agent_name}/versions

Request body:

Field	Type	Required	Description
bump	"major" | "minor"	Yes	Version increment type
prompt_text	string	Yes	The updated prompt text
notes	string	No	Change notes or rationale
activate	boolean	No	If true, immediately activate this version. Default: false

Example — create a minor version and activate it:

curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent/versions \
  -H "Content-Type: application/json" \
  -b "auth-alpha=<your-session-token>" \
  -d '{
    "bump": "minor",
    "prompt_text": "You are an expert commercial insurance agent. Always be concise...",
    "notes": "Added conciseness instruction",
    "activate": true
  }'

---

Update a Version

Updates the prompt text or notes on an existing version. The version number does not change.

PUT /agentic-flow-gateway/prompts/{agent_name}/versions/{version}

Request body:

Field	Type	Required	Description
prompt_text	string	No	Replacement prompt text
notes	string	No	Replacement notes

Example:

curl -X PUT https://<host>/agentic-flow-gateway/prompts/main_agent/versions/1.2 \
  -H "Content-Type: application/json" \
  -b "auth-alpha=<your-session-token>" \
  -d '{
    "notes": "Revised: addresses edge case in NAICS classification"
  }'

---

Activate a Version

Sets a specific version as the active prompt for the agent. Any previously active version becomes a draft.

POST /agentic-flow-gateway/prompts/{agent_name}/activate/{version}

Example:

curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent/activate/1.0 \
  -b "auth-alpha=<your-session-token>"

---

Deactivate All Versions

Deactivates all versions for an agent, reverting agent behavior to the global default.

DELETE /agentic-flow-gateway/prompts/{agent_name}/activate

Example:

curl -X DELETE https://<host>/agentic-flow-gateway/prompts/main_agent/activate \
  -b "auth-alpha=<your-session-token>"

---

Delete a Version

Deletes a specific draft version. Active versions cannot be deleted — deactivate first.

DELETE /agentic-flow-gateway/prompts/{agent_name}/versions/{version}

Example:

curl -X DELETE https://<host>/agentic-flow-gateway/prompts/main_agent/versions/1.2 \
  -b "auth-alpha=<your-session-token>"

---

Get Change History

Returns an audit trail of all changes made to a prompt for an agent, sorted by most recent first.

GET /agentic-flow-gateway/prompts/{agent_name}/history

Query parameters:

Parameter	Type	Required	Description
version	string	No	Filter to a specific version
limit	integer	No	Number of records to return. Range: 1–500. Default: 50

Response:

{
  "agent_name": "main_agent",
  "tenant_id": "acme-inc",
  "history": [
    {
      "agent_name": "main_agent",
      "tenant_id": "acme-inc",
      "version": "2.1",
      "action": "update",
      "prompt_text": "...",
      "notes": "Improved context handling",
      "is_active": true,
      "changed_at": "2025-07-12T14:22:00+00:00",
      "changed_by": "bob@example.com",
      "previous_updated_at": "2025-07-01T09:00:00+00:00",
      "previous_updated_by": "alice@example.com"
    }
  ]
}

action values:

Value	Meaning
update	Prompt text or notes were modified
delete	Version was deleted
deactivate	Version was deactivated

---

Compare Versions (Diff)

Returns a unified diff of two prompt versions for an agent.

GET /agentic-flow-gateway/prompts/{agent_name}/diff?v1={version}&v2={version}

Query parameters:

Parameter	Type	Required	Description
v1	string	Yes	The base version
v2	string	Yes	The version to compare against

Example:

curl "https://<host>/agentic-flow-gateway/prompts/main_agent/diff?v1=1.0&v2=1.1" \
  -b "auth-alpha=<your-session-token>"

---

Get Fallback Prompt

Returns the global default prompt for an agent — the prompt used when no tenant-scoped version is active.

GET /agentic-flow-gateway/prompts/{agent_name}/fallback

Data Model

Prompt Object

Field	Type	Description
agent_name	string	The agent this prompt is for
tenant_id	string	Your tenant identifier
version	string	Version in MAJOR.MINOR format
is_active	boolean	Whether this version is currently active
prompt_text	string	The full system prompt text
notes	string \| null	Optional change notes
created_at	string	ISO 8601 UTC timestamp
updated_at	string	ISO 8601 UTC timestamp
created_by	string \| null	User who created this version
updated_by	string \| null	User who last updated this version

Error Responses

Status	Cause
401	Missing or expired session cookie
404	Agent name not found, or version does not exist
409	Version already exists (e.g., creating 1.0 when it already exists)
422	Invalid request body (missing required fields, invalid bump type, etc.)

Common Workflows

Create and activate your first prompt

curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent \
  -H "Content-Type: application/json" \
  -b "auth-alpha=<your-session-token>" \
  -d '{
    "prompt_text": "You are an expert commercial insurance agent helping brokers find the right coverage for their clients...",
    "notes": "Initial prompt",
    "activate": true
  }'

Draft a new version, review it, then promote

# 1. Create a draft (do not activate yet)
curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent/versions \
  -H "Content-Type: application/json" \
  -b "auth-alpha=<your-session-token>" \
  -d '{
    "bump": "minor",
    "prompt_text": "You are an expert commercial insurance agent...",
    "notes": "Draft: testing revised instructions"
  }'

# 2. Review what changed relative to the active version
curl "https://<host>/agentic-flow-gateway/prompts/main_agent/diff?v1=1.0&v2=1.1" \
  -b "auth-alpha=<your-session-token>"

# 3. Activate when ready
curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent/activate/1.1 \
  -b "auth-alpha=<your-session-token>"

Roll back to a previous version

# Activate a prior version — it becomes the active prompt immediately
curl -X POST https://<host>/agentic-flow-gateway/prompts/main_agent/activate/1.0 \
  -b "auth-alpha=<your-session-token>"