Agent Node | Vellum | Documentation

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-4o”, “claude-3.5-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.

Extra Context

If you are planning to move between the UI and your IDE (via vellum workflows push), you should use the following folder structure for best results:

workflow.py
inputs.py # Optional inputs for your Workflow
- nodes/
  - init.py # Exports all of your nodes under all
  - prompt_node.py # A node (e.g. a Prompt Node)
  - templating_node.py # Another node (e.g. a Templating Node)
- agent/
  - init.py # Your actual agent implementation is in the init.py file.
  - add.py # Function Tool
  - subtract/ # Inline Subworkflow Tool
    - init.py
    - workflow.py
    - inputs.py
    - nodes/
      - templating.py # Node for the Subworkflow Tool

1	# nodes/agent/__init__.py
2	from typing import List
3	from vellum import (
4	ChatMessage,
5	ChatMessagePromptBlock,
6	PlainTextPromptBlock,
7	PromptParameters,
8	RichTextPromptBlock,
9	VariablePromptBlock,
10	)
11	from vellum.workflows.nodes.displayable.tool_calling_node.node import ToolCallingNode
12	from vellum.workflows.types.definition import ComposioToolDefinition, DeploymentDefinition
13	from ...inputs import Inputs
14
15	class Agent(ToolCallingNode):
16	ml_model = "gpt-5"
17	prompt_inputs = {
18	"chat_history": Inputs.chat_history,
19	}
20	blocks = [
21	ChatMessagePromptBlock(
22	chat_role="SYSTEM", blocks=[RichTextPromptBlock(blocks=[PlainTextPromptBlock(text="""Assist the user""")])]
23	),
24	VariablePromptBlock(input_variable="chat_history"),
25	]
26	parameters = PromptParameters(
27	stop=[],
28	temperature=0,
29	max_tokens=1000,
30	top_p=1,
31	top_k=0,
32	frequency_penalty=0,
33	presence_penalty=0,
34	logit_bias={},
35	custom_parameters=None,
36	)
37	settings = {
38	"stream_enabled": True,
39	}
40	max_prompt_iterations = 5
41	functions = [
42	add, # Function Tool
43	DeploymentDefinition(deployment="multiply", release_tag="LATEST"), # Deployment Tool
44	Subtract, # Workflow Tool
45	ComposioToolDefinition( # Composio Tool
46	toolkit="notion",
47	action="NOTION_ADD_PAGE_CONTENT",
48	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.",
49	user_id="abc123",
50	),
51	]
52	class Outputs(ToolCallingNode.Outputs):
53	text: str
54	chat_history: List[ChatMessage]

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