Do I need all fields in a blueprint?

No. Only agent_name and at least one tool (with a name and description) are required. All other fields — workflow, constraints, metadata, graph — are optional. However, more complete blueprints produce better test scenarios and higher readiness scores.

Create & Upload a Blueprint

Q: Can I update a blueprint after uploading?

Yes. Re-uploading a blueprint for the same agent_name updates the existing agent rather than creating a duplicate. The MCP tool and dashboard both detect existing agents and perform an update automatically.

Create a blueprint describing your agent’s tools, workflows, and constraints — then upload it to Invarium.

Key Takeaways

✓A blueprint is a structured description of your agent's tools, workflows, and constraints — how Invarium understands your agent
✓Three creation methods: generate from code via IDE assistant (YAML), write manually, or use the dashboard wizard (JSON)
✓Upload triggers an automatic readiness audit with 16 checks across 4 categories

Why It Matters

A blueprint is a structured YAML document that describes your AI agent’s tools, workflow chains, constraints, and guardrails — enabling Invarium to generate targeted behavioral tests and audit your agent’s architecture.

Without a blueprint, Invarium has no way to know what your agent does, what tools it calls, or what rules it should follow. The blueprint is the foundation for everything else: test generation, readiness audits, the Agent Intelligence Graph, and failure classification.

Blueprint Structure Overview

A blueprint is a structured document with up to 8 top-level fields. Only agent_name and at least one entry in tools are required — everything else is optional but improves test quality and audit accuracy.

The MCP path (IDE assistant) uses YAML format. The dashboard import path uses JSON format. Both describe the same schema.

agent_name: customer-support-agent
framework: langchain
description: Handles customer inquiries via knowledge base search.
tools: [ ... ]
workflow: { ... }
constraints: [ ... ]
sample_data: { ... }
metadata: { ... }

Field Reference

Required Fields

Field	Type	Description
`agent_name`	`string`	Unique identifier for your agent (e.g., `"customer-support-agent"`). Used as the primary key when uploading — re-uploading the same name updates the existing agent.
`tools`	`array`	At least one tool object is required. Each tool must have a `name` and `description`.

Tool Object Fields

Each entry in tools[] describes a function or API your agent can call.

Field	Type	Required	Description
`name`	`string`	Yes	Tool function name (e.g., `"search_knowledge_base"`).
`description`	`string`	Yes	What this tool does. Used by Invarium to generate test scenarios.
`parameters`	`object`	No	JSON Schema object describing the tool’s input parameters. Use `properties` for individual params and `required` for mandatory ones.
`returns`	`string`	No	Description of what the tool returns.
`side_effects`	`array`	No	List of side effects this tool produces. Valid values: `database_write`, `database_read`, `api_call`, `email_send`, `file_write`, `file_read`, `payment`, `notification`, `none`.
`requires_confirmation`	`boolean`	No	Whether this tool requires user confirmation before executing. Defaults to `false`.
`error_handling`	`string`	No	How errors are handled. Valid values: `retry`, `fallback`, `none`.

Optional Sections

Field	Type	Description
`framework`	`string`	The agent framework used. Recognized values: `langchain`, `crewai`, `autogen`, `openai_agents`, `custom`. Leave empty if unknown.
`framework_version`	`string`	Version of the framework (e.g., `"0.1.40"`).
`description`	`string`	A human-readable description of what your agent does.
`workflow`	`object`	Describes multi-step processes your agent performs. Contains `entry_point` (string) and `chains` (array of chain objects).
`constraints`	`object` or `array`	Rules and guardrails your agent follows. As an object: `{ system_prompt_summary, guardrails[], rate_limits{}, max_retries }`. As an array: list of constraint strings.
`sample_data`	`object`	Real values from the agent’s database for test case generation. Maps parameter names to arrays of valid values. See Sample Data below.
`metadata`	`object`	Additional context. Contains `generated_by`, `generated_at`, and `confidence` (computed automatically).

Workflow Chain Object

Each entry in workflow.chains[] describes a sequence of steps.

Field	Type	Required	Description
`name`	`string`	Yes	Chain identifier (e.g., `"purchase-flow"`).
`steps`	`array`	No	Ordered list of step descriptions.
`condition`	`string`	No	When this chain activates (e.g., `"Customer requests a refund"`).

Sample Data

The sample_data field provides real values from the agent’s database that the scenario generator uses when creating test cases. Without it, the generator invents placeholder IDs that will fail on any database lookup.

YAML format (MCP path):

sample_data:
  product_ids: ["LAPTOP-001", "PHONE-002", "HEADPHONES-003"]
  user_ids: ["user-123"]
  payment_method_ids: ["pm_visa_001", "pm_mastercard_002"]
  category: ["electronics", "clothing", "books"]

JSON format (dashboard import):

{
  "sample_data": {
    "product_ids": ["LAPTOP-001", "PHONE-002", "HEADPHONES-003"],
    "user_ids": ["user-123"],
    "payment_method_ids": ["pm_visa_001", "pm_mastercard_002"],
    "category": ["electronics", "clothing", "books"]
  }
}

Map the parameter names that your tools use for database lookups (IDs, lookup keys) to arrays of valid values. Skip free-text parameters like query or description — the scenario generator handles those fine without hints.

When creating a blueprint via the MCP path, the IDE assistant searches your codebase for real values in seed files, fixtures, test files, and mock data before asking you to provide them. See Step 3: Discover Sample Data in the MCP workflow below.

Constraints Object

The constraints field accepts two formats:

Object format (recommended for detailed blueprints):

{
  "system_prompt_summary": "You are a customer support agent...",
  "guardrails": [
    "Never fabricate information not in the knowledge base",
    "Always cite source articles"
  ],
  "rate_limits": { "requests_per_minute": 60 },
  "max_retries": 3
}

Array format (simpler):

[
  "Never fabricate information not in the knowledge base",
  "Always cite source articles"
]

Validation Rules

Invarium validates every blueprint before accepting it. Validation catches structural errors before upload so nothing is saved until the blueprint passes.

Schema Validation

Rule	Details
`agent_name` required	Must be a non-empty string.
`tools` must be an array	If present, each entry must be an object with `name` and `description`.
`framework` must be recognized	If provided, must be one of: `langchain`, `crewai`, `autogen`, `openai_agents`, `openai`, `custom`.
`error_handling` must be valid	If provided on a tool, must be one of: `retry`, `fallback`, `none`.
`side_effects` must be recognized	Each entry must be one of: `database_write`, `database_read`, `api_call`, `email_send`, `file_write`, `file_read`, `payment`, `notification`, `none`.
`workflow.chains` must be an array	If present, each chain must be an object with a `name`.
`constraints` must be object or array	Both formats are accepted.

Confidence Scoring

After validation, Invarium computes a confidence score (a measure of how complete and reliable the blueprint is) based on field completeness:

Level	Criteria	Meaning
High	Has tools AND workflow chains AND constraints	Full blueprint — Invarium can generate highly targeted tests
Medium	Has tools AND (workflow OR constraints)	Partial blueprint — tests will cover core behavior but may miss workflow-specific edge cases
Low	Tools only, or partial detection	Minimal blueprint — expect generic test scenarios

Confidence is computed automatically — you do not set it. To raise your confidence from low to high, add workflow chains and constraints to your blueprint.

Readiness Audit

Every upload triggers an automatic readiness audit (a static analysis that scores your agent’s architecture for production safety). The audit runs 16 checks across 4 categories:

Category	Budget	What It Checks
Security	50 points	Secret exposure, tool permissions, unguarded paths, unguarded external access
Reliability	25 points	Error handling, retry logic, fallback behavior, timeout config, circular dependencies, missing error recovery
System Design	15 points	System prompt presence, guardrails, output constraints
Tool Quality	10 points	Tool completeness (descriptions, parameters, return types), input validation, unreachable tools

The audit produces an Agent Readiness Score (ARS) from 0 to 100. Higher scores indicate safer, more production-ready architectures:

Score Range	Rating	Meaning
61-100	Green	Ready for production testing
31-60	Yellow	Needs improvement in specific areas
0-30	Red	Significant gaps — address critical findings before testing

Each finding includes the specific issue, its severity (critical, high, medium, or low), and what to fix. Severity weights determine the point deduction: critical = 8 points, high = 4, medium = 2, low = 1.

How to Create and Upload

Dashboard Wizard

The web dashboard at app.invarium.dev provides two paths for creating an agent: a guided 4-step wizard and a JSON import option.

Open the Agent Wizard

Navigate to Agents in the sidebar and click Create Agent. You will see two options:

Manual Registration — a step-by-step wizard that walks you through 4 steps: Identity, Capabilities, Connection, and Review
Import JSON Blueprint — paste or upload a complete blueprint JSON file

Select Manual Registration and click Continue to start the wizard.

Step 1: Identity

Fill in your agent’s identity:

Name (required) — minimum 2 characters. Use a descriptive slug like customer-support-agent or travel-booking-agent.
Description — what your agent does in one or two sentences.
System Prompt — paste your agent’s system prompt. This maps to the constraints.system_prompt_summary field in the blueprint and is used by the audit to check for guardrails.

Step 2: Capabilities

Define your agent’s tools and constraints:

Tools (at least 1 required): Click Add Tool and fill in the tool name, description, and parameters. For each parameter, specify the name, type (string, number, integer, boolean, object, or array), description, and whether it is required.

Constraints (optional but recommended): Click Add Constraint and enter a rule (e.g., “Never process refunds over $500 without manager approval”) and an optional description.

Step 3: Connection (optional)

Configure how Invarium connects to your agent for live testing:

Endpoint URL — your agent’s HTTP endpoint
Auth Type — None, API Key, Basic, Bearer, or OAuth2
Auth Config — credentials for the selected auth type

This step is optional. You can skip it and add connection details later.

Step 4: Review and Register

Review all entered information across Identity, Capabilities, and Connection. Click Edit on any section to make changes.

When everything looks correct, click Register Agent. The dashboard creates the agent and redirects you to a success screen with two options:

View Agent Details — see the agent’s dashboard page, readiness audit, and intelligence graph
Create Scenario — jump directly to generating test scenarios for this agent

JSON Import Path

If you already have a blueprint JSON file (written manually or exported from a teammate), select Import JSON Blueprint on the Create Agent screen. Paste or upload your JSON, and the dashboard validates and creates the agent in a single step. Note: the MCP path produces YAML — convert to JSON if you want to import via the dashboard.

MCP Path (IDE Assistant)

The MCP path uses two tools in sequence: invarium_prepare_blueprint to validate and preview locally, then invarium_upload_blueprint to push to the Invarium backend. Nothing is sent to the server until you explicitly confirm the upload.

Generate a blueprint from your codebase

Ask your IDE assistant to analyze your code and create a blueprint:

"Analyze my agent codebase and create an Invarium blueprint."

The assistant reads the blueprint template from invarium://templates/agent-blueprint, scans your source files for tool definitions, system prompts, and workflow logic, then generates a YAML blueprint.

You can also write the YAML manually and ask the assistant to validate it.

Prepare and preview

The assistant calls invarium_prepare_blueprint to validate the blueprint locally. This step:

Parses and validates the JSON against the schema
Computes the confidence score based on field completeness
Runs all 16 audit checks and computes the Agent Readiness Score
Saves the blueprint to .invarium/<agent_name>_blueprint.json for review

Example output:

Blueprint preview for "customer-support-agent"

  Agent: customer-support-agent
  Description: Handles customer inquiries via knowledge base search
  Framework: langchain
  Tools (2): search_knowledge_base, escalate_to_human
  Workflow chains: 1
  Confidence: high

Agent Readiness Score: 82/100 (Green)

  Category          Score    Potential
  Security:         45/50    +5 recoverable
  Reliability:      20/25    +5 recoverable
  System Design:    12/15    +3 recoverable
  Tool Quality:      5/10    +5 recoverable

Review the findings and fix any issues to improve your score. Re-run prepare to see updated results.

Discover sample data

Before uploading, the assistant searches your codebase for real values to populate the sample_data field — IDs, names, and other lookup keys that exist in your database. This step is performed automatically by scanning seed files, fixtures, test files, and mock data.

If no sample data is found automatically, the assistant will ask you to provide examples for any parameters your tools use for database lookups (e.g., product_id, user_id).

The resulting sample_data block is added to your blueprint:

sample_data:
  product_ids: ["LAPTOP-001", "PHONE-002"]
  user_ids: ["user-123"]
  payment_method_ids: ["pm_visa_001"]

Adding sample data significantly improves the accuracy of generated test scenarios — tests will use real IDs instead of invented placeholders that fail on database lookups.

Upload to Invarium

Once satisfied, confirm and the assistant calls invarium_upload_blueprint:

"Upload this blueprint to Invarium."

Expected output:

Blueprint uploaded for customer-support-agent
Tools detected: 2
Workflow chains: 1
Confidence: high
View on dashboard: https://app.invarium.dev/agent/<agent-id>

If an agent with the same name already exists, the upload updates the existing agent rather than creating a duplicate.

The MCP prepare step runs entirely locally — no data is sent to the Invarium backend until you explicitly call upload. This lets you iterate on your blueprint privately before registering.

Blueprint Examples

Example 1: Minimal Blueprint — Just the essentials

The bare minimum needed to register an agent. Provides low confidence and basic test generation.

{
  "agent_name": "customer-support-agent",
  "tools": [
    {
      "name": "search_knowledge_base",
      "description": "Search the internal knowledge base for articles matching a customer query."
    }
  ]
}

Confidence: Low — has tools only, no workflow or constraints.

Example 2: Intermediate Blueprint — Adds constraints and a description for medium confidence

Intermediate Blueprint

Adds constraints and a description. Provides medium confidence and more targeted tests.

{
  "agent_name": "customer-support-agent",
  "framework": "langchain",
  "description": "Handles customer inquiries by searching a knowledge base and providing accurate, cited answers.",
  "tools": [
    {
      "name": "search_knowledge_base",
      "description": "Search the internal knowledge base for articles matching a customer query.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Search terms from the customer's question" },
          "category": { "type": "string", "description": "Optional category filter (billing, technical, general)" }
        },
        "required": ["query"]
      },
      "returns": "Array of matching articles with title, content snippet, and relevance score.",
      "side_effects": ["database_read"],
      "error_handling": "fallback"
    },
    {
      "name": "escalate_to_human",
      "description": "Transfer the conversation to a human support agent.",
      "parameters": {
        "type": "object",
        "properties": {
          "reason": { "type": "string", "description": "Why the conversation is being escalated" },
          "priority": { "type": "string", "description": "Escalation priority: low, medium, high" }
        },
        "required": ["reason"]
      },
      "returns": "Confirmation with ticket ID and estimated wait time.",
      "side_effects": ["notification"],
      "requires_confirmation": true,
      "error_handling": "retry"
    }
  ],
  "constraints": [
    "Never fabricate information not found in the knowledge base",
    "Always cite the source article title when answering",
    "Escalate to a human agent if confidence is below 70%",
    "Do not discuss topics outside the product domain"
  ]
}

Confidence: Medium — has tools and constraints, but no workflow chains.

Example 3: Full Blueprint — Complete with tools, workflows, constraints, and metadata for high confidence

Full Blueprint

A complete blueprint with tools, workflows, constraints, and metadata. Provides high confidence and the most targeted test generation.

{
  "agent_name": "travel-booking-agent",
  "framework": "openai_agents",
  "framework_version": "1.0.2",
  "description": "An AI travel assistant that searches flights, checks availability, and books trips with payment processing and confirmation.",
  "tools": [
    {
      "name": "search_flights",
      "description": "Search for available flights between two airports on a given date range.",
      "parameters": {
        "type": "object",
        "properties": {
          "origin": { "type": "string", "description": "Departure airport IATA code (e.g., SFO)" },
          "destination": { "type": "string", "description": "Arrival airport IATA code (e.g., JFK)" },
          "departure_date": { "type": "string", "description": "Departure date in YYYY-MM-DD format" },
          "return_date": { "type": "string", "description": "Optional return date for round trips" },
          "passengers": { "type": "integer", "description": "Number of passengers (1-9)" }
        },
        "required": ["origin", "destination", "departure_date"]
      },
      "returns": "Array of available flights with airline, times, stops, and price.",
      "side_effects": ["api_call"],
      "error_handling": "retry"
    },
    {
      "name": "check_seat_availability",
      "description": "Check real-time seat availability and class options for a specific flight.",
      "parameters": {
        "type": "object",
        "properties": {
          "flight_id": { "type": "string", "description": "Unique flight identifier from search results" },
          "seat_class": { "type": "string", "description": "Seat class: economy, business, first" }
        },
        "required": ["flight_id"]
      },
      "returns": "Available seat count, price per class, and seat map.",
      "side_effects": ["api_call"],
      "error_handling": "fallback"
    },
    {
      "name": "book_flight",
      "description": "Book a flight and process payment for the specified passengers.",
      "parameters": {
        "type": "object",
        "properties": {
          "flight_id": { "type": "string", "description": "Flight to book" },
          "passengers": {
            "type": "array",
            "description": "List of passenger objects with name, date_of_birth, and passport_number"
          },
          "payment_method_id": { "type": "string", "description": "Stored payment method identifier" },
          "seat_class": { "type": "string", "description": "Seat class: economy, business, first" }
        },
        "required": ["flight_id", "passengers", "payment_method_id"]
      },
      "returns": "Booking confirmation with confirmation_code, itinerary, and receipt.",
      "side_effects": ["payment", "email_send", "database_write"],
      "requires_confirmation": true,
      "error_handling": "fallback"
    },
    {
      "name": "cancel_booking",
      "description": "Cancel an existing flight booking and initiate a refund if eligible.",
      "parameters": {
        "type": "object",
        "properties": {
          "confirmation_code": { "type": "string", "description": "Booking confirmation code" },
          "reason": { "type": "string", "description": "Cancellation reason" }
        },
        "required": ["confirmation_code"]
      },
      "returns": "Cancellation status with refund amount and timeline.",
      "side_effects": ["payment", "email_send", "database_write"],
      "requires_confirmation": true,
      "error_handling": "retry"
    }
  ],
  "workflow": {
    "entry_point": "user_request",
    "chains": [
      {
        "name": "booking-flow",
        "steps": [
          "Parse travel request for origin, destination, dates, and passengers",
          "Search for available flights matching criteria",
          "Present flight options to the user",
          "Check seat availability for the selected flight",
          "Confirm booking details and total price with the user",
          "Process payment and create the booking",
          "Send confirmation email with itinerary"
        ],
        "condition": "User wants to book a flight"
      },
      {
        "name": "cancellation-flow",
        "steps": [
          "Look up the booking by confirmation code",
          "Check cancellation eligibility and refund policy",
          "Confirm cancellation with the user",
          "Process cancellation and initiate refund",
          "Send cancellation confirmation email"
        ],
        "condition": "User wants to cancel a booking"
      }
    ]
  },
  "constraints": {
    "system_prompt_summary": "You are a travel booking assistant. Help users search, book, and manage flight reservations. Always verify details before processing payments.",
    "guardrails": [
      "Always check seat availability before attempting to book",
      "Never process a booking without explicit user confirmation of the total price",
      "Do not store or display full passport numbers — show only the last 4 digits",
      "Refuse bookings for more than 9 passengers per transaction",
      "Always present the cancellation policy before confirming a cancellation"
    ],
    "rate_limits": {
      "flight_searches_per_minute": 30,
      "bookings_per_hour": 10
    },
    "max_retries": 3
  },
  "metadata": {
    "generated_by": "ide_template",
    "generated_at": "2026-03-27T00:00:00Z",
    "confidence": "high"
  }
}

Confidence: High — has tools, workflow chains, and constraints.

Frequently Asked Questions

Can I update a blueprint after uploading?

Yes. Re-uploading a blueprint with the same agent_name updates the existing agent rather than creating a duplicate. Both the MCP tool and the dashboard detect existing agents and perform an update automatically. Your test history, scenarios, and audit trail are preserved — only the blueprint definition is replaced.

What is the maximum blueprint size?

500 KB. Most blueprints are well under this limit — a full blueprint with 10 tools, 5 workflows, and detailed constraints is typically under 10 KB.

Do I need all fields?

No. Only agent_name and at least one tool (with a name and description) are required. All other fields — workflow, constraints, metadata, framework — are optional. However, more complete blueprints produce better test scenarios and higher readiness scores. See the confidence scoring section for how completeness affects test quality.

What happens if validation fails?

Invarium returns specific error messages for each validation failure. Common examples:

Error	Fix
`Missing required field: agent_name`	Add an `agent_name` string to the root of your blueprint
`Missing required field: tools[0].name`	Every tool must have a `name` field
`Missing required field: tools[0].description`	Every tool must have a `description` field
`Unknown framework: 'xyz'`	Use a recognized framework value: `langchain`, `crewai`, `autogen`, `openai_agents`, `openai`, or `custom`
`tools[0].error_handling: invalid value`	Use `retry`, `fallback`, or `none`
`tools[0].side_effects: unknown effect`	Use recognized values: `database_write`, `database_read`, `api_call`, `email_send`, `file_write`, `file_read`, `payment`, `notification`, `none`

The MCP prepare step and dashboard preview both catch errors before upload, so nothing is saved to the server until validation passes. Fix the listed issues and re-submit.

Quickstart Framework Integration