Block Agent Basics
This guide describes the benefits and components of Block Agents. Learn more about:
Overview
The Block Agent workflow uses a graph data structure, allowing you to build complex agents in a simpler way. You can configure a Block Agent to respond to multiple topics and move through steps within each topic. Build via JSON input defining each component of the workflow, one Block Agent can simplify unwieldy SmartFlows projects and provide overall improved performance.
Block Agents vs. Other Agent Types
A Block Agent workflow is ideal for complex use cases and can address some key challenges when building other types of agents.
Key Differences with a Block Agent
-
Two parallel LLM calls at each turn.
-
One call triggers functions, the second call produces and AI response.
-
-
Always fires at least one tool.
-
At least one tool will always be defined for each block.
-
There will always be a tool triggered.
-
Tools have the ability to trigger multiple tools at a given turn.
-
-
Structured prompting approach.
-
Through a standardized approach and format for prompting, higher performing AI agents can be created.
-
Key Challenges Addressed with a Block Agent
-
Prompt Bloat
-
Due to excessive instructions packed into a single prompt, prompt bloat often results in suboptimal outcomes in various forms.
-
Block Agent prompts are refined by our experts and cannot be edited.
-
-
Standardized Prompting
-
The lack of a standardized approach to prompting can throw off the delicate balance between creativity and science within prompt design.
-
Block Agents highlight the advantage of a scientific, structured methodology in prompt creation.
-
-
Function Call Latency and Accuracy
-
Prompt bloat and lack of standardization both directly impact the reliability of function calls, leading to inaccurate outcomes or functions not being triggered as intended.
-
The use of consecutive or double function calls in agent design also introduces additional latency.
-
-
Rules Based Design Approach
-
For other agent types, rules or tasks are embedded directly in the system prompt, contributing to prompt bloat.
-
Block Agents introduce an alternative method for defining these rules (via blocks), allowing you to enforce operational guardrails and boundaries more effectively. This agent type also opens up the potential to gain insights into turn-based telemetry.
-
Block Agent Features
Block Agents combine some elements you’re probably already familiar with when building other agent types (tools, prompts, etc.), with some powerful new components (blocks, turns, and edges).
Main Components
-
-
A "topic" within a conversation.
-
-
-
The individual steps that are executed in a conversation.
-
-
-
Move the conversation on from a Turn.
-
-
-
Determine how the Edge is evaluated (can the conversation move on and where does it go next)?
-
-
-
Enable your agent to perform a subsequent action based on the user's action.
-
-
-
Optional definition of specific variables and settings produced as a result of a given Turn.
-
-
-
The Block Agent System Prompt is standardized, defined and managed by the AI Team.
-
-
-
Variables that are populated at run time.
-
-
-
Values passed to achieve specific behavior.
-
-
-
Provide further context to your agent.
-
Blocks
The main "topics" your agent is able to address. Each Block is focused on one topic and can contain multiple Turns, Edges, Tools, Settings, etc.
Your Block might look like this:
{
"block_id": "intent",
"name": "Intent",
"turns": [ ... ],
"tools": [ ... ],
"settings": { ... }
},
Turns
The individual steps that are executed in a conversation. Block Agents support two types of Turns:
-
Turns with no wait condition.
-
This is basically the default type of Turn. No special handling is applied to this Turn. The system executed the Turns and traverses the defined Edges.
-
-
Turns with a wait condition.
-
The agent will remain paused at a specific Turn and not proceed until the condition for the “wait_token” is satisfied.
-
Include “type”: ”wait_token” (e.g., “transfer_to_agent”).
-
SmartFlows designers can implement a Switch statement to determine the outcome.
-
Your Turn might look like this:
{
"turn_id": "0",
"turn_name": "Personalized Greeting and Intent Detection",
"content": " If the user has scheduled prior rides, you must Thank them for calling Alivi Healthcare and ask them if they would like to schedule a new ride. If the user has never scheduled a ride, you must welcome them to Alivi Healthcare and ask how you can help them. You do not need to collect any information about upcoming healthcare appointments from the user at this point.",
"edges": [... ]
}
Edges
To move on from a Turn, the Block Agent will need to exit on an Edge. Edges evaluate where the conversation should go next, and each Turn is comprised of zero to many Edges.
Note: If a Turn has zero Edges, we can consider this Turn to be the terminus of the conversation.
Block Agents support two types of Edges:
-
Edge
-
The standard type recommended for most use cases.
-
“type”: “edge”
-
-
Loop
-
Use this type to re-prompt or retry when none of the conditions are met.
-
“type”: “loop”
-
Note: A Turn can only have one Edge with the “loop” type. This ensures that fallback behavior is clearly defined and does not cause multiple conflicting re-prompt scenarios.
Every Edge will have one or more Conditions associated with it that tell the model whether or not it has been satisfied, and a Condition to either move to another Turn or a Block.
Block Agents move through each Edge in the order they are written and evaluate the Edge’s Conditions. As soon as an Edge’s Conditions are satisfied, the agent will follow that Edge, without evaluating any further Edges. This gives you, the builder, some control over situations where multiple Edge’s Conditions might be satisfied at once.
To handle problematic conversational event (e.g., asking an unrelated question, not giving a response, etc.), we recommend including a single looping Edge (i.e., “type”: “loop”) in most of your Turns as the final Edge.
Your Edge might look like this:
{
"edge_id": "0",
"edge_name": "Schedule New Ride Intent Detected",
"type": "edge",
"condition": {
"source": "tools",
"expected_value": {
"schedule_new_ride": "*"
},
"out_response": {
"success": "Thank you! I'd be happy to help you schedule transportation.",
"failure": "I am sorry, having trouble understanding you, are you calling about a new ride or cancel an already scheduled ride?",
"timeout": ""
}
},
"messages": [
"Id be happy to help you schedule transportation."
],
"connect_to": {
"turn_id": "901"
}
}, You can also include an Operator value in your Edge. Block Agents support two types of Edge Operators:
-
And
-
The default operation, followed if you don’t include an Operator value.
-
All elements of the “expected_value” object must be true in order for the Edge to be considered true.
-
“operator”: “and”
-
-
Or
-
If any of the “expected_value” elements are true, then the Edge is considered true.
-
“operator”: “or”
-
Your Edge with an Operator might look like this:
{
"edge_id": "0",
"type": "edge",
"condition": {
"source": "tools",
"expected_value": {
"pizza_toppings": "*",
"pizza_size": "*",
"operator": "or"
},
"out_response": {
"success": "Thank you!",
"failure": "I didn't get that. What Toppings and/or size would u like for ur pizza?",
"timeout": ""
}
},
"messages": [],
"connect_to": {
"turn_id": "3"
}
}
Conditions
The Conditions defined within an Edge determiner how the Edge is evaluated. Conditions guide the agent’s decisions by assessing input data or external responses. If the Conditions are met, the agent proceeds along the defined Edge to the next Turn or Block.
Block Agents support two types of Conditions:
-
Evaluates Expressions
-
The expressions in a JSON object are evaluated.
-
The following properties are required:
-
Source
-
Specifies the source of the data to be evaluated. Supported values are:
-
Tools: Data collected from tool calls within a Block (i.e., “tools”).
-
External: External data provided by the user, such as results from an authentication API, payment status, etc. (i.e., “external”).
-
-
-
Expected Value
-
Defines the expected result against which the source data is compared. This field supports case-insensitive string equality with wildcard matching (i.e., *).
-
The Condition is considered met when the source data matches the expected value (i.e., “expected_value”).
-
-
Out Response
-
A list of predefined responses that the agent can use based on the evaluation result (i.e., “out_response”).
-
These responses typically include “success”, “failure”, and “timeout”.
-
While optional, providing these responses is recommended as they help guide the language model and prevent hallucinations.
-
-
-
-
Loop-Based Condition (Natural Language Understanding (NLU))
-
This Condition type is typically used for Edges with the “type”: “loop”, designed for fallback scenarios where the agent’s response relies on understanding natural language input. These conditions leverage LLMs and NLU capabilities to determine the appropriate next action.
-
Note: The Condition types are mutually exclusive. You cannot mix both Condition types within a single Turn. The only exception to this rule is when an Edge is a “loop” type. In this case, a Loop-Based Condition is allowed alongside an Evaluated Expressions Condition. This enables fallback scenarios where both structured evaluation and NLU can be used.
Your Condition might look like this:
{
"edge_id": "0",
"type": "edge",
"condition": {
"source": "tools",
"expected_value": {
"pizza_toppings": "*",
"pizza_size": "*",
"operator": "and"
},
"out_response": {
"success": "Thank you!",
"failure": "I didn't get that. What Toppings and/or size would u like for ur pizza?",
"timeout": ""
}
},
"messages": [],
"connect_to": {
"turn_id": "3"
}
}
Tools
Tools in a Block Agent behave the same as in a GPT or SAM Agent. But there are a few special things to keep in mind when building your Block Agent:
-
Multiple Tools can be triggered at a single Turn.
-
For example, if you created a Tool that captures a caller’s name and a Tool that captures a caller’s date of birth, and a caller says, “My name is Jane Doe and I was born on May 5 1990”, we would expect that both Tools would trigger at that Turn.
-
-
The Block Agent makes two, parallel calls to the LLM at each Turn.
-
One call will produce an AI Response. The second call will trigger all appropriate Tools.
-
The LLM will always pick from one of the available Tools. Even if all choices are poor, it will attempt to select the best Tool from the available choices.
-
For example, if you “prime” an agent with an initial “hi” message for intent detection, and the available Tools at this step describe the known intent values, the model is going to pick an intent and move on to the next step (even if we are just using the primer message of “hi”). To get around this, we recommend including a function like “caller_intent_not_yet_detected”.
-
Currently, the only type of Tool Block Agent supports is function (i.e., “type”: “function”).
Your Tool might look like this:
"tools": [
{
"type": "function",
"function": {
"name": "schedule_new_ride",
"description": "Detect when user wants to book transportation. No information collection needed at this stage.",
"parameters": {
"type": "object",
"properties": {}
}
}
},
{
"type": "function",
"function": {
"name": "cancel_ride",
"description": "Detect when user wants to cancel an existing scheduled ride.",
"parameters": {
"type": "object",
"properties": {}
}
}
}
]
Settings
You can define specific Setting that should be produced as the result of a given Turn.
Note: This is optional and does not change the behavior of the Block Agent.
Settings information is provided in the API Response Body when calling the /agent/{agent_id}/response endpoint.
Use Settings to update ASR and TTS actions with optimized modes and configurations that are relevant to your specific use case/task. You can define any object and value you choose. The examples below show ASR and Hermes Settings, but they are not the only available possibilities.
Your Settings might look like this:
{
"block_id": "intent",
"name": "Intent",
"turns": [ ... ],
"tools": [ ... ],
"settings": {
"hermes": {
"some_setting": "some_value",
"some_other_setting": "some_other_value"
}
}
}, And the API Response Body might look like this:
"settings": {
"hermes": {
"some_setting": "some_value",
"some_other_setting": "some_other_value"
}
} Keep in mind the following when using Settings:
-
AI Hub does not execute any specific logic in the presence or absence of Settings.
-
Settings can optionally be defined for a Block.
-
If defined, at each Turn during this Block, the Settings will be provided in the API Response.
-
If not defined, no Settings are returned in the API Response.
-
-
Settings can optionally be defined for a Turn.
-
This will override settings that were defined at the Block level.
-
System Prompt
Unlike the other AI Agent types, the Block Agent System Prompt is not editable.
The System Prompt is managed by the AI Team. As we learn more and continue benchmarking, we expect that the System Prompt will continue to evolve.
Although the prompt is not editable, you can pass in runtime information via the {arg_context} variable.
The default System Prompt looks like this:
At run time, the AI Hub includes additional information in the System Prompt. This would include the personality content, all flow arguments, information about the current Turn and adjacent Turns that are possibly next in the conversation.
It might look like this:
Flow Arguments
Use Arguments to pass in variables that are populated at run time.
The format {arg_X} communicates to the AI Hub that a variable is being declared and will need to be substituted at runtime. Arguments are passed to the AI Hub in the Request Body of the API call.
As mentioned above, you cannot modify the System Prompt, but you may need to add some context to the LLM via the {arg_context} variable. We recommend using this variable to add data from an external system or other dynamic content to the System Prompt.
Note: If the context is not relevant or useful for later turns in the conversation, make sure to clear this value before subsquent calls to the AI Hub.
Other possible Arguments could include:
-
Dynamic information about the business
-
Dynamic information about the caller (e.g., name, date of birth, etc.)
-
Information about the time of day
Block Agents support Arguments being included in the following locations:
-
Personality Block
-
Turn content
-
Message in Turns
-
System Prompt Context
Query Parameters
You can pass various query parameters to your Block Agent/response endpoint to achieve specific behavior.
-
Customer ID
-
This is a required parameter and must match an Agent ID for your Customer Account.
-
-
Session ID
-
We recommend passing the same Session ID for the whole conversation that a specific Block Agent provides automation for.
-
Sometimes multiple agents in a single SmartFlow will have unique Session IDs provided to them. Make sure to use the same Session ID for the entirety of a conversation.
-
-
Group Session ID
-
We recommend all AI Agents in a SmartFlows session will be provided the same Group Session ID.
-
This enables grouping conversations and improves the viewability in the AI Hub’s Conversation History page.
-
-
Safe Characters
-
Some characters are difficult for TTS engines to play (e.g., newline characters or double quotes).
-
Passing the “enable_response_filter” parameter with a value of true, strips the newline and double quote characters from the “ai_response” content.
-
-
Debug
-
To gain insights and visibility into the executed System Prompt at a specific Turn, pass in a debug parameter to display the fully populated System Prompt.
-
This will include the Personality, values for Flow Arguments, retrieved Knowledge Content, and Turn information.
-
Pass the parameter “debug” with a value of true.
-
This parameter is optional.
-
-
Non-Default Entry Turn
-
This parameter is specific to Block Agents.
-
By default, each conversation beings with the first Turn defined in the JSON configuration. However, in some cases you might want to start at a different Turn. For example, when the business is closed and we want a different experience or where we have additional context about the caller and want to provide a more personalized experience.
-
Pass the parameter “entry_turn_id” with a value for an existing turn_id. If the turn_id is not valid, the agent will produce an error in the API Response Body.
-
This parameter is optional.
-
Knowledge Collections
You can configure Knowledge Collections available to all Blocks or specific to one Block within your agent. Details about your Knowledge Collection are defined within the Settings, and should include:
-
Knowledge Collection Name
-
For example, “context_source_colelction”: “Product_Catalogue”.
-
-
Context Threshold
-
For example, “context_threshold”: 0.2.
-
-
Number of Results to Return
-
For example, “answers_count_threshold”: 1.
-
Recommended value is typically 1.
-
Note: You can only define one Knowledge Collection. Currently we do no support the ability to provide a Knowledge Collection for the entire agent and then another Knowledge Collection Specific to a Block. We do not support FAQ Knowledge Collection types. If you require this use case we recommend chunking your Q&A pairs and uploading them to the Knowledge Collection database. We do not support Knowledge Collections for specific Turns within a Block.
Knowledge Collection Available to All Blocks
When your Knowledge Collection is available for all of the Blocks in your agent, at each turn in each block the AI Hub will query the Knowledge Collection and add retrieved information to the executed system prompt.
Your Knowledge Collection might look like this:
...
"settings": {
"system_prompt": "...",
"user_prompt": "{user_message}",
"functions": null,
"tools": null,
"vendor_id": "intelepeer",
"model_name": "gpt-3-5-turbo-intelepeer",
"task": "dialog",
"sliding_window_size": 2,
"special_instruction": "",
"knowledge_collections": [
{
"context_source_collection": "AI_Taxi_Test_1",
"context_threshold": 0.2
}
],
"blocks": [ ... ]
}
...Knowledge Collection Available to a Specific Block
When your Knowledge Collection is available for a specific Block in your agent, all Turns inside of the specific Block will query the Knowledge Collection.
Your Knowledge Collection might look like this:
...
"blocks": [
{
"block_id": "intent",
"name": "Intent",
"turns": [ ... ],
"tools": [ ... ],
"knowledge_collections": [
{
"context_source_collection": "AI_Taxi_Test_1",
"context_threshold": 0.2,
"answers_count_threshold": 1
}
]
},
...
]
Now that you’ve learn a little bit about the benefits of Block Agents and the important components they contain, check out: