Skip to main content

​
Dynamic System Prompts

Agents support dynamic system prompts that can include live data through template functions. These functions are executed each time the agent runs, providing fresh context. Use {module::function} syntax to embed dynamic values: 
agent = Agent(
    name="dynamic_agent",
    model="openai/gpt-4o-mini",
    system_prompt="""You are a time-aware assistant.
    Current time: {datetime::datetime.now}."""
)
The previous example used a built-in function (datetime). You can also create your own custom functions: 
# my_functions.py
def get_server_status():
    """Get server status."""
    status = check_server()  # Calls external function
    return f"Server: {status}"

agent = Agent(
    name="custom_agent", 
    model="openai/gpt-4o-mini",
    system_prompt="""You are a helpful assistant.
    Status: {my_functions::get_server_status}."""
)
You can also pass dynamic parameters to these functions using RunContext data that you previously set in the context. 
# my_functions.py
from timbal.core import Tool, Agent
from timbal.state import get_run_context

def get_user_language():
    span = get_run_context().current_span()
    return span.input["language"]

def set_user_language(l):
    span = get_run_context().current_span()
    span.input["language"] = "catalan"

agent = Agent(
    name="multilang_agent",
    model="openai/gpt-4o-mini",
    pre_hook=set_user_language,
    system_prompt="Answer in {my_functions::get_user_language}."
)

await agent(prompt="Which is the capital of Germany?").collect()
The response will be in Catalan. Benefits:
  • Real-time context: System prompts reflect current state
  • Dynamic behavior: Agent adapts to changing conditions
  • Automatic execution: Functions run on each conversation
  • Performance: Template resolution is fast and cached
  • Sync/Async: Handles both sync and async functions automatically

​
Dynamic Tools via ToolSets

Timbal supports dynamic tool resolution through ToolSets. Instead of providing a static list of tools, you can define a ToolSet that determines which tools are available based on runtime conditions. Tool availability must be implemented in the resolve() method, which returns a list of Runnable tools. 
from timbal import Agent, Tool, ToolSet

class RoleBasedToolSet(ToolSet):
    """ToolSet that provides different tools based on user role."""    
    role: str

    async def resolve(self) -> list[Tool]:
        """Dynamically resolve tools based on the user's role."""
        
        if self.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-4o-mini",
    tools=[RoleBasedToolSet(role="admin")]  # ToolSet resolved at runtime
)