Understanding Agents

Master proven strategies for designing advanced, specialized AI agents that work together seamlessly to tackle complex challenges.

---

What is an Agent?

An Agent is like having your own AI-powered teammate—one that can understand your goals, reason about the best way to achieve them, and take actions on your behalf. Powered by advanced Large Language Models (LLMs), Agents go far beyond simple chatbots or assistants.

Think of an Agent as:

• A digital coworker that can read, write, and analyze information.
• A problem-solver that can break down complex tasks into steps and execute them.
• A connector that can use tools, access APIs, search the web, or interact with other software to get things done.

Agent()  # That's it! You've created your first agent!

Note: Make sure to define all required environment variables—such as your OpenAI API key, your Gemini API key, the API key model that you need—in your .env file.

.env

OPENAI_API_KEY=your_api_key_here

Quick Example

Here's an example of an agent that uses a tool to get weather information:

from timbal import Agent, Tool

# Define a weather tool
def get_weather(location: str) -> str:
  # This is a simplified example - in practice, you'd use a real weather API
  return "The weather is sunny"

# Create an agent with the weather tool
agent = Agent(
  model="gemini-2.5-pro-preview-03-25",
  tools=[
      Tool(
          runnable=get_weather,
          description="Get the weather for a specific location",
      )
  ]
)

# Use the agent to get weather information
response = await agent.complete(
  prompt="What's the weather like in New York?"
)

Agent Execution Logs:

StartEvent(..., path='agent, ...)

OutputEvent(..., path='agent.llm-0', ...)

OutputEvent(...,
  path='agent.llm-0', 
  input={
    'messages': [
      Message(
        role=user,
        content=[TextContent(
          type='text', 
          text="What's the weather like in New York?"
        )]
      )
    ], 
    'tools': [{
      'type': 'function', 
      'function': {
        'name': 'get_weather',
        'description': 'Get the weather for a specific location',
        'parameters': {
          'properties': {'location': {'title': 'Location', 'type': 'string'}}, 
          'required': ['location'],
          ...
        }
      }
    }], 
    'model': 'gpt-4',
    ...
  },
  output=Message(
    role=assistant,
    content=[ToolUseContent(
      type='tool_use', 
      id='...', 
      name='get_weather', 
      input={'location': 'New York'}
    )]
  ), ...)

StartEvent(..., path='agent.get_weather-call_...', ...)

OutputEvent(..., path='agent.get_weather-...)

OutputEvent(...,
  path='agent.get_weather-...',
  input={'location': 'New York'},
  output=Message(
    role=user,
    content=[TextContent(type='text', text='The weather is sunny')]
  ), ...)

StartEvent(..., path='agent.llm-1', ...)

OutputEvent(..., path='agent.llm-1', ...)

OutputEvent(...,
  path='agent.llm-1', 
  input={
    'messages': [
      Message(
        role=user, 
        content=[TextContent(
          type='text',
          text="What's the weather like in New York?"
        )]
      ), 
      Message(
        role=assistant, 
        content=[ToolUseContent(
          type='tool_use',
          id='...',
          name='get_weather',
          input={'location': 'New York'}
        )]
      ),
      Message(
        role=user, 
        content=[ToolResultContent(
          type='tool_result', 
          id='call_...', 
          content=[TextContent(type='text', text='The weather is sunny')]
        )]
      )
    ],
    'tools': [{
      'type': 'function', 
      'function': {
        'name': 'get_weather',
        'description': 'Get the weather for a specific location',
        'parameters': {
          'properties': {'location': {'title': 'Location', 'type': 'string'}},
          'required': ['location'],
          ...
        }
      }
    }], 
    'model': 'gpt-4',
    ...
  },
  output=Message(
    role=assistant, 
    content=[TextContent(
      type='text',
      text='The weather in New York is sunny.'
    )]
  ),...)

OutputEvent(..., path='agent', ...)

OutputEvent(...,
  path='agent',
  input={
    'prompt': {
      'role': 'user', 
      'content': [{
        'type': 'text',
        'text': "What's the weather like in New York?"
      }]
    }
  },
  output=Message(
    role=assistant, 
    content=[TextContent(
      type='text',
      text='The weather in New York is sunny.'
    )]
  ), ...)

This example shows how to create an agent with a custom tool. The agent can now use the weather tool to fetch real-time weather data when needed. You can add multiple tools to make your agent even more powerful!

Key Capabilities of an Agent

Let's break down how an Agent thinks and works:

Autonomous Reasoning

Agents can decide what to do next based on your instructions and the current situation.

Tool Use

They can use built-in or custom tools (like searching the internet, fetching data, or running code) to accomplish tasks.

Memory

Agents can remember previous interactions, decisions, or data, allowing them to work on long-term or multi-step projects.

Adaptability

They can handle a wide range of tasks, from answering questions to automating workflows.

Running an Agent

To execute an Agent, there are 2 possibilities depending on the synchronisation.

Get a Complete Answer

For when the agent returns a complete response after processing. We will use the complete() function:

response = await agent.complete(prompt="What time is it?")

Real-Time (Streaming) Output

Otherwise, when we want to know specific information on each event we can find the response asynchrounsly by running run():

response = async for event in agent.run(prompt="What time is it?"):
  print(event) 

Events tell you what's happening in your agent. Here's what you can do with them:

async for event in agent.run(prompt="What time is it?"):
  if event.type == "START":
      print(f"Starting Agent: {event.step_id}")

async for event in agent.run(prompt="What time is it?"):
  if event.type == "OUTPUT":
      print(f"Agent finished in {event.elapsed_time}ms")
      print(f"Outputs: {event.outputs}")

Next Steps

• Try creating your own Agent with different tools
• Experiment with different configurations
• See an example agent in Examples

Remember: The more you practice, the better you'll become at creating powerful Agents!