Dynamic Agents

Dynamic System Prompts

Agents support dynamic system prompts through callable functions that are executed each time the agent runs, providing fresh context.

Using Callable Functions

The preferred way to create dynamic system prompts is to pass a callable directly to system_prompt. This gives you full control over the system prompt construction and access to all runtime inputs:

from datetime import datetime
from timbal import Agent
from timbal.state import get_run_context

def get_system_prompt() -> str:
    run_context = get_run_context()
    current_span = run_context.current_span()
    
    now = datetime.now()
    date_str = now.strftime("%A, %B %d, %Y")
    time_str = now.strftime("%H:%M")

    system_prompt = f"You're a helpful assistant. Current date: {date_str}. Current time: {time_str}."

    # Access runtime inputs
    instructions = current_span.input.get("instructions", None)
    if instructions:
        system_prompt += f"\n\n## Instructions\n{instructions}"

    user = current_span.input.get("user", None)
    if isinstance(user, dict):
        system_prompt += "\n\n## About the User\n"
        for k, v in user.items():
            if isinstance(v, list):
                system_prompt += f"\n- {k}:"
                for item in v:
                    system_prompt += f"\n  - {item}"
            else:
                system_prompt += f"\n- {k}: {v}"

    return system_prompt

agent = Agent(
    name="dynamic_agent",
    model="openai/gpt-5-mini",
    system_prompt=get_system_prompt,  # Pass the function directly
)

Then call the agent with runtime data:

response = await agent(
    prompt="Who am I?",
    instructions="Be concise and friendly.",
    user={
        "name": "Alice",
        "role": "Developer",
        "memories": [
            "Prefers Python over JavaScript",
            "Working on a new project",
        ],
    },
).collect()

String placeholders are not resolved

A string system_prompt is sent as written. {module::function} is not implemented: {datetime::datetime.now} and {my_functions::get_server_status} stay as literal text. The callable form above is the way to build the prompt at runtime. Read the current call from span.input inside that callable. Passed as language="catalan", this prompt tells the model to answer in Catalan:

from timbal import Agent
from timbal.state import get_run_context

def system_prompt() -> str:
    language = get_run_context().current_span().input.get("language", "English")
    return f"Answer in {language}."

agent = Agent(
    name="multilang_agent",
    model="openai/gpt-5-mini",
    system_prompt=system_prompt,
)

await agent(prompt="Which is the capital of Germany?", language="catalan").collect()

Benefits:

Real-time context: the callable runs on every turn and sees that call’s input
Dynamic behavior: the prompt can follow language, user, or instructions passed into the call
Sync or async: the callable can be either

Dynamic Tools

Timbal provides the ToolSet class for dynamic tool resolution. ToolSets resolve tools at runtime before each LLM call, enabling dynamic tool availability based on execution context. Use ToolSets instead of static tool lists when:

Context-dependent availability: Tools should only appear under certain conditions (user permissions, environment state, iteration count)
Lazy loading: Defer tool initialization until actually needed
Dynamic configuration: Tools need runtime parameters or state that isn’t known at agent creation
Conditional behavior: Tool availability changes during execution
Token efficiency: Reduce token consumption by exposing only relevant tools instead of all available tools
Improved clarity: When many tools exist but only a few are available per context, the agent sees fewer options and is less likely to get confused

Implement the resolve() method to return a list of tools. Access runtime data through get_run_context() to inspect the current execution state.

Example: Role-based tool access

This example shows accessing input parameters to conditionally provide tools. The role can be set via prehook or when calling the agent:

from timbal import Agent, Tool
from timbal.core.tool_set import ToolSet
from timbal.state import get_run_context

def view_profile() -> str:
    """View the current user profile."""
    return "profile"

def delete_user(user_id: str) -> str:
    """Delete a user by id."""
    return f"deleted {user_id}"

def modify_permissions(user_id: str, role: str) -> str:
    """Change a user's role."""
    return f"{user_id} -> {role}"

class RoleBasedToolSet(ToolSet):
    async def resolve(self) -> list[Tool]:
        span = get_run_context().current_span()
        role = span.input.get("role", "user")

        if role == "admin":
            return [
                Tool(handler=view_profile),
                Tool(handler=delete_user),
                Tool(handler=modify_permissions)
            ]
        else:
            return [Tool(handler=view_profile)]


admin_agent = Agent(
    name="admin_agent",
    model="openai/gpt-5-mini",
    tools=[RoleBasedToolSet()]
)

# Role can be set via prehook or as a parameter
await admin_agent(prompt="Delete user 123", role="admin").collect()

The resolve() method is called before each LLM call. It reads the role from the input parameters and returns different tools:

role == "admin": returns view_profile, delete_user, modify_permissions
Otherwise: returns only view_profile

The agent only sees the tools returned by resolve(), preventing unauthorized actions when the role is not “admin”.

Getting started

Core Concepts

Agents

Voice Agents

Workflows

Human in the Loop

Evals

Deployment

Dynamic Agents

Dynamic System Prompts

Using Callable Functions

String placeholders are not resolved

Dynamic Tools

Example: Role-based tool access

​Dynamic System Prompts

​Using Callable Functions

​String placeholders are not resolved

​Dynamic Tools

​Example: Role-based tool access

Dynamic System Prompts

Using Callable Functions

String placeholders are not resolved

Dynamic Tools

Example: Role-based tool access