​
Overview

The Agent class is the central component for creating conversational AI agents in Kapso. It manages the graph structure, nodes, edges, and configuration of your agent.

​
Complete example

from kapso.builder import Agent
from kapso.builder.nodes import SubagentNode, HandoffNode, WarmEndNode
from kapso.builder.agent.constants import START_NODE, END_NODE

# Create agent with system prompt
agent = Agent(
    name="support_bot",
    system_prompt="""You are a helpful customer support assistant for ACME Corp.
    Be professional, empathetic, and solution-oriented.
    Always verify customer information before making changes.""",
    message_debounce_seconds=3
)

# Add required special nodes
agent.add_node(START_NODE)
agent.add_node(END_NODE)

# Create main subagent node
subagent = SubagentNode(
    name="assistant",
    prompt="Help the customer with their inquiry"
)
agent.add_node(subagent)

# Add global handoff for escalation
handoff = HandoffNode(
    name="human_handoff",
    global_=True,
    global_condition="user is angry or requests human"
)
agent.add_node(handoff)

# Add conversation end node
end = WarmEndNode(
    name="end_conversation",
    timeout_minutes=30,
    prompt="Thank you for contacting support!"
)
agent.add_node(end)

# Define conversation flow
agent.add_edge(START_NODE, "assistant")
agent.add_edge("assistant", "end_conversation", condition="issue resolved")
agent.add_edge("end_conversation", END_NODE)

# Validate the agent structure
agent.validate()

​
Import

from kapso.builder import Agent
from kapso.builder.agent.constants import START_NODE, END_NODE

​
Constructor

Agent(
    name: str,
    system_prompt: str = None,
    message_debounce_seconds: int = None
)

​
Parameters

  • name (str, required): The unique name for your agent. Must be alphanumeric with underscores.
  • system_prompt (str, optional): The system-level instructions that define the agent’s behavior, personality, and rules.
  • message_debounce_seconds (int, optional): Time in seconds to wait before processing messages to handle rapid user inputs.

​
Example

agent = Agent(
    name="customer_support_bot",
    system_prompt="""You are a helpful customer support assistant for ACME Corp.
    Be professional, empathetic, and solution-oriented.
    Always verify customer information before making changes.""",
    message_debounce_seconds=2
)

​
Properties

​
nodes

agent.nodes  # List[Node]

Returns a list of all nodes in the agent graph.

​
edges

agent.edges  # List[Edge]

Returns a list of all edges (connections) between nodes.

​
Methods

​
add_node()

agent.add_node(node: Node) -> None

Adds a node to the agent graph.

Parameters:

  • node: Any node instance (DefaultNode, SubagentNode, etc.)

Example:

from kapso.builder.nodes import DefaultNode

greeting = DefaultNode(
    name="greeting",
    prompt="Welcome the user and ask how you can help"
)
agent.add_node(greeting)

​
add_edge()

agent.add_edge(
    source: str,
    target: str,
    condition: str = None
) -> None

Creates a connection between two nodes.

Parameters:

  • source (str): The name of the source node or START_NODE
  • target (str): The name of the target node or END_NODE
  • condition (str, optional): Natural language condition for when this edge should be followed

Example:

# Simple edge
agent.add_edge(START_NODE, "greeting")

# Conditional edge
agent.add_edge("greeting", "order_status", condition="user asks about their order")
agent.add_edge("greeting", "product_info", condition="user asks about products")

​
validate()

agent.validate() -> None

Validates the agent graph structure. Checks for:

  • Presence of START_NODE and END_NODE
  • All nodes are reachable from START_NODE
  • No circular dependencies (except through global nodes)
  • Valid node names and configurations

Raises:

  • ValidationError: If the graph structure is invalid

Example:

try:
    agent.validate()
    print("Agent is valid!")
except ValidationError as e:
    print(f"Validation failed: {e}")

​
remove_node()

agent.remove_node(node_name: str) -> None

Removes a node and all its associated edges from the graph.

Parameters:

  • node_name (str): The name of the node to remove

​
get_node()

agent.get_node(node_name: str) -> Node

Retrieves a node by its name.

Parameters:

  • node_name (str): The name of the node to retrieve

Returns:

  • The node instance if found, None otherwise

​
Special nodes

Every agent must include these special nodes:

​
START_NODE

from kapso.builder.agent.constants import START_NODE

agent.add_node(START_NODE)

The entry point of the agent. Must have exactly one outgoing edge.

​
END_NODE

from kapso.builder.agent.constants import END_NODE

agent.add_node(END_NODE)

The exit point of the agent. Can have multiple incoming edges.