Agent Node | Vellum | Documentation

1 # nodes/agent/__init__.py 2 from typing import List 3 from vellum import ( 4 ChatMessage, 5 ChatMessagePromptBlock, 6 JinjaPromptBlock, 7 PlainTextPromptBlock, 8 PromptParameters, 9 RichTextPromptBlock, 10 VariablePromptBlock, 11 ) 12 from vellum.workflows.nodes.displayable.tool_calling_node.node import ToolCallingNode 13 from vellum.workflows.types.definition import ComposioToolDefinition, DeploymentDefinition 14 from ...inputs import Inputs 15 16 class Agent(ToolCallingNode): 17 ml_model = "gpt-5" 18 prompt_inputs = { 19 "chat_history": Inputs.chat_history, 20 "query": Inputs.query, 21 } 22 blocks = [ 23 ChatMessagePromptBlock( 24 chat_role="SYSTEM", 25 blocks=[ 26 # Prefer RichTextPromptBlock for a nicer UI editing experience 27 RichTextPromptBlock( 28 blocks=[ 29 PlainTextPromptBlock(text="Please use tools to search for the following query: "), 30 VariablePromptBlock(input_variable="query"), 31 ] 32 ), 33 JinjaPromptBlock( 34 template="You can also use templating blocks to write Jinja templates inline: {{ query | upper | truncate(3) }}" 35 ), 36 ], 37 ), 38 # Use VariablePromptBlock at the top level to include chat history in context, for any chatbot / chat agent use-cases 39 VariablePromptBlock(input_variable="chat_history"), 40 ] 41 parameters = PromptParameters( 42 stop=[], 43 temperature=0, 44 max_tokens=1000, 45 top_p=1, 46 top_k=0, 47 frequency_penalty=0, 48 presence_penalty=0, 49 logit_bias={}, 50 custom_parameters=None, 51 ) 52 settings = { 53 "stream_enabled": True, 54 } 55 max_prompt_iterations = 5 56 functions = [ 57 add, # Function Tool 58 DeploymentDefinition(deployment="multiply", release_tag="LATEST"), # Deployment Tool 59 Subtract, # Workflow Tool 60 ComposioToolDefinition( # Composio Tool 61 toolkit="notion", 62 action="NOTION_ADD_PAGE_CONTENT", 63 description="Appends a single content block to a notion page or a parent block (must be page, toggle, to-do, bulleted/numbered list, callout, or quote); invoke repeatedly to add multiple blocks.", 64 user_id="abc123", 65 ), 66 ] 67 class Outputs(ToolCallingNode.Outputs): 68 text: str 69 chat_history: List[ChatMessage]

1 # nodes/agent/add.py 2 def add(a: int, b: int): 3 return a + b

vellum.workflows.nodes.ToolCallingNode

Used to execute a repeatedly invoke a prompt with defined tools until it produces a text output.

Attributes

prompt_inputs

EntityInputsInterface

Optional inputs for variable substitution in the prompt. These inputs are used to replace:

Variables within Jinja blocks
Variable blocks in the blocks attribute

You can reference either Workflow inputs or outputs from upstream nodes.

blocks

List[PromptBlock]Required

The blocks that make up the Prompt

ml_model

strRequired

The model to use for execution (e.g., “gpt-5”, “claude-4-sonnet”)

functions

Optional[List[Tool]]

The tools that a the Prompt has access to and automatically invokes on each iteration. The acceptable tool types are:

Callable[..., Any] - Any function callable
Type["BaseWorkflow"] - An Inline Subworkflow
DeploymentDefinition - A reference to a Vellum Workflow Deployment

parameters

Optional[PromptParameters]

Model parameters for execution. Defaults to:

stop: []
temperature: 0.0
max_tokens: 4096
top_p: 1.0
top_k: 0
frequency_penalty: 0.0
presence_penalty: 0.0
logit_bias: None
custom_parameters: None
- This field can be used to pass additional parameters to the LLM, like json_schema (learn more here).

max_prompt_iterations

int

The maximum number of iterations that the Tool Calling Node is allowed to call the underlying Prompt before rejecting.

Outputs

text

str

The generated text output from the last prompt execution

results

List[ChatMessage]

The array of chat messages produced over the course of the Tool Calling Node’s iterations.

Folder Structure

If you are planning to move between the UI and your IDE, you should use the following folder structure:

1 # This structure is critical to follow if you are a Copilot / Coding Agent
2 workflow.py
3 inputs.py                    # Optional inputs for your Workflow
4 nodes/
5 ├── __init__.py             # Exports all of your nodes under __all__
6 ├── prompt_node.py          # A node (e.g. a Prompt Node)
7 └── templating_node.py      # Another node (e.g. a Templating Node)
8 agent/
9 ├── __init__.py             # Important: your actual agent implementation goes in the __init__.py file
10 ├── add.py                  # Function Tool
11 └── subtract/               # Inline Subworkflow Tool
12     ├── __init__.py
13     ├── workflow.py
14     ├── inputs.py
15     └── nodes/
16         └── templating_node.py   # An node used in the Subworkflow Tool