Agent Extensions

Overview

The Prompty agent loop (see Agent Mode) supports six optional extensions that give you fine-grained control over every iteration. All extensions are opt-in — pass only the ones you need.

Extension	Purpose	Parameter
Events	Observe loop activity (tool calls, errors, etc.)	on_event / onEvent
Cancellation	Cooperatively abort a running loop	cancel / signal / cancellationToken
Context Window	Auto-trim messages to fit the model’s context	context_budget / contextBudget
Guardrails	Validate input, output, and tool calls	guardrails
Steering	Inject user messages mid-loop	steering
Parallel Tools	Execute tool calls concurrently	parallel_tool_calls / parallelToolCalls

Additionally, each runtime provides a typed tool decorator/attribute that turns a regular function into a registered tool.

Execution Order (per iteration)

1. Check cancellation
2. Drain steering messages
3. Trim context window
4. Input guardrail
5. Check cancellation (again, before LLM call)
6. Call LLM
7. Output guardrail
8. Tool guardrails (per tool)
9. Execute tools (serial or parallel)
10. Format tool results → append to messages

---

Events

Subscribe to structured events emitted during the agent loop. Event callbacks must not block — exceptions are silently swallowed to keep the loop running.

Python

from prompty import invoke_agent, load
from prompty.core import AgentEvent, EventCallback

def my_callback(event: AgentEvent) -> None:
    print(f"[{event.event_type}] {event.data}")

agent = load("agent.prompty")
result = invoke_agent(
    agent,
    inputs={"question": "Hello"},
    tools={"get_weather": get_weather},
    on_event=my_callback,
)

TypeScript

import { load, invokeAgent } from "@prompty/core";

const agent = await load("agent.prompty");
const result = await invokeAgent(agent, { question: "Hello" }, {
  tools: { get_weather: getWeather },
  onEvent: (eventType, data) => {
    console.log(`[${eventType}]`, data);
  },
});

C#

using Prompty.Core;

var agent = PromptyLoader.Load("agent.prompty");
var result = await Pipeline.InvokeAgentAsync(
    agent,
    new() { ["question"] = "Hello" },
    tools: tools,
    onEvent: (eventType, data) =>
    {
        Console.WriteLine($"[{eventType}] {string.Join(", ", data)}");
    }
);

Event Types

Event	When	Data
tool_call_start	Before each tool executes	name, arguments
tool_result	After each tool executes	name, result
status	Informational (e.g., steering injected)	message
messages_updated	Messages array changed	messages
done	Loop completed normally	response, messages
error	A guardrail denied or error occurred	message
cancelled	Loop was cancelled	iteration

---

Cancellation

Cooperatively cancel a running agent loop. The loop checks for cancellation at the top of each iteration and just before the LLM call.

Python

import threading
from prompty import invoke_agent, load
from prompty.core import CancellationToken

token = CancellationToken()

# Cancel from another thread after 5 seconds
threading.Timer(5.0, token.cancel).start()

try:
    result = invoke_agent(agent, inputs, tools, cancel=token)
except CancelledError:
    print("Agent loop was cancelled")

TypeScript

import { invokeAgent, CancelledError } from "@prompty/core";

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const result = await invokeAgent(agent, inputs, {
    tools,
    signal: controller.signal,
  });
} catch (err) {
  if (err instanceof CancelledError) {
    console.log("Agent loop was cancelled");
  }
}

C#

using Prompty.Core;

var cts = new CancellationTokenSource();

// Cancel after 5 seconds
cts.CancelAfter(TimeSpan.FromSeconds(5));

try
{
    var result = await Pipeline.InvokeAgentAsync(
        agent, inputs, tools,
        cancellationToken: cts.Token
    );
}
catch (OperationCanceledException)
{
    Console.WriteLine("Agent loop was cancelled");
}

Note

Python uses a custom CancellationToken (wrapping threading.Event), TypeScript uses the native AbortSignal, and C# uses the native System.Threading.CancellationToken.

---

Context Window Management

Automatically trim messages to fit within a character budget. The trimmer preserves system messages and the most recent conversation turns, replacing dropped messages with a compact summary.

Python

result = invoke_agent(
    agent,
    inputs={"question": "Summarize our conversation"},
    tools=tools,
    context_budget=50_000,  # characters
)

TypeScript

const result = await invokeAgent(agent, inputs, {
  tools,
  contextBudget: 50_000,
});

C#

var result = await Pipeline.InvokeAgentAsync(
    agent, inputs, tools,
    contextBudget: 50_000
);

How Trimming Works

1. Estimate the character cost of all messages (role overhead + text + tool call JSON)
2. Partition into leading system messages vs. the rest
3. Drop the oldest non-system messages until within budget (keeping at least 2)
4. Summarize dropped messages into a compact [Context summary: ...] block
5. Inject the summary as a user message after the system messages

Tip

A good rule of thumb is to set context_budget to about 75% of your model’s context window size (in characters, not tokens). This leaves room for the model’s response.

---

Guardrails

Validate messages at three checkpoints in the loop: before the LLM call (input), after the LLM responds (output), and before each tool executes (tool). If a guardrail denies, a GuardrailError is raised.

Python

from prompty.core import Guardrails, GuardrailResult, GuardrailError

def check_input(messages):
    """Block prompt injection attempts."""
    for msg in messages:
        if "ignore previous instructions" in msg.text.lower():
            return GuardrailResult(allowed=False, reason="Prompt injection detected")
    return GuardrailResult(allowed=True)

def check_tool(name, args):
    """Only allow known-safe tools."""
    if name == "delete_all_data":
        return GuardrailResult(allowed=False, reason="Dangerous tool blocked")
    return GuardrailResult(allowed=True)

guardrails = Guardrails(input=check_input, tool=check_tool)

try:
    result = invoke_agent(agent, inputs, tools, guardrails=guardrails)
except GuardrailError as e:
    print(f"Blocked: {e.reason}")

TypeScript

import { Guardrails, GuardrailError } from "@prompty/core";

const guardrails = new Guardrails({
  input: (messages) => {
    for (const msg of messages) {
      if (msg.text.toLowerCase().includes("ignore previous instructions")) {
        return { allowed: false, reason: "Prompt injection detected" };
      }
    }
    return { allowed: true };
  },
  tool: (name, args) => {
    if (name === "delete_all_data") {
      return { allowed: false, reason: "Dangerous tool blocked" };
    }
    return { allowed: true };
  },
});

try {
  const result = await invokeAgent(agent, inputs, { tools, guardrails });
} catch (err) {
  if (err instanceof GuardrailError) {
    console.log(`Blocked: ${err.reason}`);
  }
}

C#

using Prompty.Core;

var guardrails = new Guardrails(
    input: (messages) =>
    {
        foreach (var msg in messages)
        {
            if (msg.Text.Contains("ignore previous instructions", StringComparison.OrdinalIgnoreCase))
                return new GuardrailResult(false, "Prompt injection detected");
        }
        return new GuardrailResult(true);
    },
    tool: (name, args) =>
    {
        if (name == "delete_all_data")
            return new GuardrailResult(false, "Dangerous tool blocked");
        return new GuardrailResult(true);
    }
);

try
{
    var result = await Pipeline.InvokeAgentAsync(
        agent, inputs, tools,
        guardrails: guardrails
    );
}
catch (GuardrailError e)
{
    Console.WriteLine($"Blocked: {e.Reason}");
}

Guardrail Checkpoints

Hook	When	Receives	Typical Use
input	Before LLM call	Full message list	Prompt injection detection, content policy
output	After LLM response	Assistant message	Toxicity filtering, PII detection
tool	Before each tool call	Tool name + args	Block dangerous operations, rate limiting

Caution

When a tool guardrail denies a call, the denied tool’s result is replaced with a synthetic error message (e.g., "Guardrail denied: reason"). The loop continues — the LLM sees the denial and can adjust.

---

Steering

Inject additional user messages into a running agent loop from outside. This is useful for human-in-the-loop scenarios where you want to redirect the agent mid-conversation.

Python

import threading
from prompty.core import Steering

steering = Steering()

def user_input_loop():
    while True:
        msg = input("You: ")
        steering.send(msg)

# Run input loop in background
threading.Thread(target=user_input_loop, daemon=True).start()

result = invoke_agent(agent, inputs, tools, steering=steering)

TypeScript

import { Steering } from "@prompty/core";

const steering = new Steering();

// Inject a message that will be picked up at the next iteration
steering.send("Actually, check Paris instead of London");

const result = await invokeAgent(agent, inputs, {
  tools,
  steering,
});

C#

using Prompty.Core;

var steering = new Steering();

// From another thread or async context
steering.Send("Actually, check Paris instead of London");

var result = await Pipeline.InvokeAgentAsync(
    agent, inputs, tools,
    steering: steering
);

At the top of each iteration, the loop calls steering.drain() to collect all pending messages and appends them to the conversation. The steering queue is thread-safe in all runtimes.

---

Parallel Tool Execution

When the LLM requests multiple tool calls in a single response, you can execute them concurrently instead of sequentially.

Python

# Async mode uses asyncio.gather for true parallelism
result = await invoke_agent_async(
    agent, inputs, tools,
    parallel_tool_calls=True,
)

TypeScript

// Uses Promise.all for concurrent execution
const result = await invokeAgent(agent, inputs, {
  tools,
  parallelToolCalls: true,
});

C#

// Uses Task.WhenAll for concurrent execution
var result = await Pipeline.InvokeAgentAsync(
    agent, inputs, tools,
    parallelToolCalls: true
);

Note

In Python sync mode, parallel_tool_calls still executes tools sequentially (Python’s GIL limits true parallelism in threads). Use the async variant for actual concurrency.

---

Combining Extensions

All extensions compose naturally. Here’s a fully-configured agent call:

Python

from prompty import invoke_agent_async, load_async
from prompty.core import (
    CancellationToken,
    Guardrails,
    GuardrailResult,
    Steering,
)

agent = await load_async("agent.prompty")
token = CancellationToken()
steering = Steering()

guardrails = Guardrails(
    input=lambda msgs: GuardrailResult(allowed=True),
    output=lambda msg: GuardrailResult(allowed=True),
    tool=lambda name, args: GuardrailResult(allowed=True),
)

result = await invoke_agent_async(
    agent,
    inputs={"question": "Plan my trip"},
    tools=tools,
    on_event=lambda e: print(f"[{e.event_type}]"),
    cancel=token,
    context_budget=50_000,
    guardrails=guardrails,
    steering=steering,
    parallel_tool_calls=True,
    max_iterations=20,
)

TypeScript

import {
  load, invokeAgent,
  Guardrails, Steering, CancelledError,
} from "@prompty/core";

const agent = await load("agent.prompty");
const controller = new AbortController();
const steering = new Steering();
const guardrails = new Guardrails({
  input: () => ({ allowed: true }),
  output: () => ({ allowed: true }),
  tool: () => ({ allowed: true }),
});

const result = await invokeAgent(agent, { question: "Plan my trip" }, {
  tools,
  onEvent: (type, data) => console.log(`[${type}]`),
  signal: controller.signal,
  contextBudget: 50_000,
  guardrails,
  steering,
  parallelToolCalls: true,
  maxIterations: 20,
});

C#

using Prompty.Core;

var agent = PromptyLoader.Load("agent.prompty");
var cts = new CancellationTokenSource();
var steering = new Steering();
var guardrails = new Guardrails(
    input: _ => new GuardrailResult(true),
    output: _ => new GuardrailResult(true),
    tool: (_, _) => new GuardrailResult(true)
);

var result = await Pipeline.InvokeAgentAsync(
    agent,
    new() { ["question"] = "Plan my trip" },
    tools: tools,
    maxIterations: 20,
    onEvent: (type, data) => Console.WriteLine($"[{type}]"),
    cancellationToken: cts.Token,
    contextBudget: 50_000,
    guardrails: guardrails,
    steering: steering,
    parallelToolCalls: true
);

---

Typed Tool Functions

The .prompty file is the single source of truth — tools are declared in frontmatter so the file is a complete, portable exchange format. The runtime needs a handler function for each declared tool. Each runtime provides a decorator or attribute that makes writing these handlers clean: you get typed parameters instead of raw JSON, and the boilerplate disappears.

The .prompty File Declares, Your Code Implements

Tools are always declared in the .prompty frontmatter — this is what gets sent to the LLM so it knows what tools are available:

# agent.prompty (frontmatter excerpt)
tools:
  - name: get_weather
    kind: function
    description: Get the current weather for a city
    parameters:
      - name: city
        kind: string
        description: City name
        required: true
      - name: units
        kind: string
        default: celsius

Your code then provides the handler — the function that actually runs when the LLM calls get_weather. This is where @tool / tool() / [Tool] helps.

Before and After

Python

# ❌ Without @tool — manual dict, raw JSON parsing
import json

def get_weather(args_json):
    args = json.loads(args_json)
    city = args["city"]
    units = args.get("units", "celsius")
    return f"72°F in {city}"

tools = {"get_weather": get_weather}

result = invoke_agent(agent, inputs, tools=tools)

# ✅ With @tool + bind_tools — typed, validated, clean
from prompty import tool, bind_tools, invoke_agent

@tool
def get_weather(city: str, units: str = "celsius") -> str:
    """Get the current weather for a city."""
    return f"72°F in {city}"

# bind_tools validates names match the .prompty declarations
tools = bind_tools(agent, [get_weather])
result = invoke_agent(agent, inputs, tools=tools)

TypeScript

// ❌ Without tool() — manual dict, untyped args
const tools = {
  get_weather: (args: Record<string, unknown>) => {
    const city = args.city as string;
    return `72°F in ${city}`;
  },
};

const result = await invokeAgent(agent, inputs, { tools });

// ✅ With tool() + bindTools — typed, validated handler
import { tool, bindTools, invokeAgent } from "@prompty/core";

const getWeather = tool(
  (city: string, units?: string) => `72°F in ${city}`,
  {
    name: "get_weather",
    description: "Get the current weather for a city",
    parameters: [
      { name: "city", kind: "string", required: true },
      { name: "units", kind: "string", default: "celsius" },
    ],
  },
);

// bindTools validates names match the .prompty declarations
const tools = bindTools(agent, [getWeather]);
const result = await invokeAgent(agent, inputs, { tools });

C#

// ❌ Without [Tool] — manual dict, manual JSON parsing
var tools = new Dictionary<string, Func<string, Task<string>>>
{
    ["get_weather"] = async (argsJson) =>
    {
        var args = JsonSerializer.Deserialize<Dictionary<string, object?>>(argsJson)!;
        var city = args["city"]?.ToString() ?? "unknown";
        var units = args.GetValueOrDefault("units")?.ToString() ?? "celsius";
        return $"72°F in {city}";
    },
};

var result = await Pipeline.InvokeAgentAsync(agent, inputs, tools: tools);

// ✅ With [Tool] + BindTools — typed parameters, validated, no JSON parsing
using Prompty.Core;

public class WeatherService
{
    [Tool(Name = "get_weather", Description = "Get the current weather")]
    public string GetWeather(string city, string units = "celsius")
    {
        return $"72°F in {city}";
    }
}

// BindTools validates [Tool] names match the .prompty declarations
var service = new WeatherService();
var tools = ToolAttribute.BindTools(agent, service);

var result = await Pipeline.InvokeAgentAsync(agent, inputs, tools: tools);

Tip

The .prompty file declares what tools exist (name, parameters, description) — this is sent to the LLM. Your code provides how they run. The decorator/attribute handles JSON deserialization so your function receives real typed parameters (string, int, bool) instead of raw JSON.

End-to-End Example

A complete agent with the .prompty file and matching handlers:

# agent.prompty
---
name: assistant
model:
  id: gpt-4o
  provider: openai
  apiType: chat
tools:
  - name: get_weather
    kind: function
    description: Get the current weather for a city
    parameters:
      - name: city
        kind: string
        required: true
  - name: get_time
    kind: function
    description: Get the current time in a timezone
    parameters:
      - name: timezone
        kind: string
        required: true
inputs:
  - name: question
    kind: string
---
system:
You are a helpful assistant with access to weather and time tools.

user:
{{question}}

Python

from prompty import load, invoke_agent, tool, bind_tools

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"72°F and sunny in {city}"

@tool
def get_time(timezone: str) -> str:
    """Get the current time in a timezone."""
    return f"3:42 PM in {timezone}"

agent = load("agent.prompty")

# bind_tools validates that each @tool name matches a declaration
# in agent.tools, then returns the handler dict
tools = bind_tools(agent, [get_weather, get_time])

result = invoke_agent(
    agent,
    inputs={"question": "What's the weather in Tokyo?"},
    tools=tools,
)
print(result)

TypeScript

import { load, invokeAgent, tool, bindTools } from "@prompty/core";

const getWeather = tool(
  (city: string) => `72°F and sunny in ${city}`,
  {
    name: "get_weather",
    description: "Get the current weather for a city",
    parameters: [{ name: "city", kind: "string", required: true }],
  },
);

const getTime = tool(
  (timezone: string) => `3:42 PM in ${timezone}`,
  {
    name: "get_time",
    description: "Get the current time in a timezone",
    parameters: [{ name: "timezone", kind: "string", required: true }],
  },
);

const agent = await load("agent.prompty");

// bindTools validates names against agent.tools declarations
const tools = bindTools(agent, [getWeather, getTime]);

const result = await invokeAgent(agent, { question: "Weather in Tokyo?" }, {
  tools,
});
console.log(result);

C#

using Prompty.Core;

public class AssistantTools
{
    [Tool(Name = "get_weather", Description = "Get the current weather")]
    public string GetWeather(string city)
    {
        return $"72°F and sunny in {city}";
    }

    [Tool(Name = "get_time", Description = "Get the current time")]
    public string GetTime(string timezone)
    {
        return $"3:42 PM in {timezone}";
    }
}

var agent = PromptyLoader.Load("agent.prompty");
var service = new AssistantTools();

// BindTools validates [Tool] methods against agent.Tools declarations
var tools = ToolAttribute.BindTools(agent, service);

var result = await Pipeline.InvokeAgentAsync(
    agent,
    new() { ["question"] = "What's the weather in Tokyo?" },
    tools: tools
);
Console.WriteLine(result);

Note

bind_tools validates that every handler name matches a kind: "function" tool declared in the agent’s frontmatter. If you typo a name or forget a declaration, you get an immediate error — not a silent runtime failure when the LLM tries to call the tool.

Customization Options

Python

# Bare decorator — uses function name and docstring
@tool
def my_func(x: str) -> str:
    """This becomes the description."""
    return x

# With overrides
@tool(name="custom_name", description="Custom description")
def my_func_v2(x: str) -> str:
    return x

# Access the generated FunctionTool definition
print(my_func.__tool__.name)        # "my_func"
print(my_func.__tool__.description)  # "This becomes the description."
print(my_func.__tool__.parameters)   # [Property(name="x", kind="string", ...)]

TypeScript

const helper = tool(fn, {
  name: "helper",
  parameters: [...],
});

// Access the generated FunctionTool
console.log(helper.__tool__.name);  // "helper"

C#

// [Tool] with no arguments — uses method name as-is
[Tool]
public string MyMethod(string x) => x;
// Tool name = "MyMethod"

// [Tool] with overrides
[Tool(Name = "custom_name", Description = "Custom description")]
public string MyMethod2(string x) => x;
// Tool name = "custom_name"

// Build a FunctionTool definition without registering
var method = typeof(MyClass).GetMethod("MyMethod")!;
var toolDef = ToolAttribute.BuildFromMethod(method);
Console.WriteLine(toolDef.Name);        // "MyMethod"
Console.WriteLine(toolDef.Parameters);  // [Property { Name = "x", Kind = "string" }]

Type Mappings

The decorator/attribute maps language types to schema kinds automatically:

Python	TypeScript	C#	Schema Kind
str	"string"	string	string
int	"integer"	int, long	integer
float	"float"	float, double	float
bool	"boolean"	bool	boolean
list	"array"	List<T>, arrays	array
dict	"object"	Dictionary<,>	object

Note

TypeScript cannot introspect types at runtime, so parameters must be declared explicitly in the tool() options. Python and C# derive the schema from the function signature automatically.