How to Migrate a Block Agent to Block Agent v2

This guide describes how to move your agent to Block Agent v2. Learn more about:

 

Note: We recommend migrating all of your Block Agents to v2, regardless of when they were created. Both existing Block Agents and newly created Block Agents must be manually migrated to v2 at this time.

 

Overview

Block Agents v2 provides significant improvements in flexibility, performance, and experience. You can create more robust, maintainable, and performant conversation AI agents with v2.

Follow these high-level steps:

  1. Migrate your agent using the steps below

  2. Add enhanced=true to your API calls (required for Jinja templates and MCP server tooling)

  3. Configure the task_jxml adapter for better structure and parsing

  4. Leverage new v2 features like entry points and improved context management

  5. Use context variables to reference Tools from prior Blocks

 

Why Should You Migrate Your Agent?

Block Agent v2 introduces several significant improvements over v1:

  • Improved System Prompts and Task Adapter

    • New System Prompt Features:

      • Deterministic State Machine: More predictable task transitions

      • Structured Instructions: Clearer task execution rules

    • Task Adapter System:

      • task_jxml Adapter: JSON-based response format providing better structure and easier parsing

      • Improved adapter system with better separation of concerns

      • Easier to extend with custom adapters

 

  • Improved Context Management

    • As the conversation moves across blocks, in the prior version, the Block Agent didn't have context about tools that were triggered in prior blocks. With Block Agent v2, you can create edges that reference fired tools that occurred earlier in the session. For instance, if you are in the ID and Auth Block and you want to go to specific Blocks once you've authenticated the user, you can reference the detected intent in the first block of the conversation.

 

Migrate Your Block Agent

You can migrate a Block Agent to Block Agent v2 by calling the AI Hub API and making two simple changes to the Agent Configuration.

 

Step 1: Call the GET Endpoint

Retrieve the current agent configuration:

GET https://aiservice.intelepeer.com/aihub/v2/agent/{agent_id}

 

Step 2: Make Two Changes to the Configuraiton

  1. Set the System Prompt to an empty string.

  2. Set the task adapter to: task_jxml.

Note: We recommend using model gpt-4.1-intelepeer going forward.

 

Step 3: Call the PUT Endpoint to Update the Agent

Update the agent configuration with the modified settings:

PUT https://aiservice.intelepeer.com/aihub/v2/agent/{agent_id}

 

Step 4: Call the POST Endpoint to Publish the Agent

Publish the migrated agent:

POST https://aiservice.intelepeer.com/aihub/v2/agent/{agent_id}/publish

 

Post-Migration

Once the agent is migrated to v2, you must use an updated query parameter at run-time when interacting with the Agent Response Endpoint: Pass a query parameter of enhanced=true.

 

Make the Most of Your v2 Block Agent

Once you've migrated your agent, you can leverage Block Agent v2 features in several ways:

  • Enable Enhanced Mode

    • Step 1: Add the enhanced=true query parameter to all agent API calls:

      POST/aiservice/v2/agent/{agent_id}/response?enhanced=true&customer_id={cust_id}&session_id={session_id}

    • Step 2: Ensure your agent configuration supports v2 features.

  • Choose the Right Adapter

    • For Structured JSON responses:

      {
	"settings": {
		"adapter": "task_jxml"
	}
}

    • Benefits:

      • Easier to parse responses programmatically

      • Better integration with frontend applications

      • More reliable response handling

  • Leverage Entry Points

    • Use Case: Direct Navigation

      # Start conversation at a specific turn POST /aiservice/v2/agent/{agent_id}/response?entry_turn_id=greeting&customer_id={customer_id}&session_id={session_id}&enhanced=true

  • Implement Personality Guidelines

    • In agent configuration:

      {
	"settings": {
		"adapter": "task_jxml",
		"personality": "You are a friendly, professional customer service representative..."
		...
	}
}

    • The Task JXML adapter automatically applies personality guidelines to all responses.

  • Use Knowledge Collections Per Block

    • Configuration:

      {
	"blocks": [
		{
			"block_id": "block-1",
			"knowledge_collections": [
				{
					"context_source_collection": "faq-collection",
					"embedding_model": "text-embedding-ada-002",
					"answers_count_threshold": 3,
					"context_threshold": 0.7
				}
			]
		}
	]
}

    • Benefits:

      • Different knowledge bases for different conversation stages

      • More relevant context retrieval

      • Better answer quality

  • Implement Agent Policies

    • Usage:

      {
	"user_message": "Hello",
	"policy": {
		"max_turns": 10,
		"timeout": 300
	}
}

 

Tips and Best Practices

  • Always Use Enhanced Mode: Set enhanced=true for all new implementations (required for Jinja templates and MCP server tooling).

  • We recommend using model "gpt-4.1-intelepeer".

  • Choose JSON Adapter: Use task_jxml for better structure and parsing.

  • Implement Entry Points: Use entry points for better user experience.

  • Leverage Knowledge Collections: Configure per-block knowledge for better context.

  • Use Context Variables: Reference tools fired in prior blocks for better conversation flow.