Weather agent with a custom Python tool

This recipe shows the smallest useful pattern for extending an agent with your own code: you write a plain Python function, register it as a custom function, wrap it in a run_python tool, and attach that tool to an agent. When the agent decides it needs live data, SeekrFlow runs your function and feeds the result back into the conversation. The example function calls a public weather API (wttr.in) and returns the forecast for a single ZIP code, so you can see the full round trip from agent to your code to a third-party service and back.

What you’ll build

An agent that:

Exposes a custom Python function as a run_python tool.
Calls the tool whenever the user asks about the weather.
Runs your function, which requests live data from an external API.
Reports back exactly what the API returned.

Prerequisites

A SeekrFlow API key, set as the SEEKR_API_KEY environment variable
Python 3.8 or later
The SeekrFlow SDK: pip install seekrai

This recipe creates billable resources. When you are done, remove them with the cleanup step.

Build it

Write the weather function

Save the following as weather_fn.py. This is an ordinary Python function with no SeekrFlow dependencies. The docstring matters: SeekrFlow uses it to tell the agent what the tool does and when to call it, so write it the way you would write a tool description.

import urllib.request
import urllib.error


def get_current_weather() -> str:
    """Get the current weather for ZIP code 22207 (Arlington, VA).

    Fetches live weather data from a public API. Always call this tool
    when the user asks about the weather or wants a weather report.

    Returns:
        str: Raw weather data from the API, or an error message.
    """
    url = "https://wttr.in/22207?0"
    try:
        req = urllib.request.Request(url, headers={"User-Agent": "curl/7.64.1"})
        with urllib.request.urlopen(req, timeout=10) as resp:
            status = resp.status
            body = resp.read().decode()
        return f"[HTTP {status}] {body}"
    except urllib.error.HTTPError as e:
        return f"[HTTPError {e.code}] {e.reason}: {e.read().decode()}"
    except urllib.error.URLError as e:
        return f"[URLError] {e.reason}"
    except Exception as e:
        return f"[Error] {type(e).__name__}: {e}"

The function catches its own errors and returns them as a string instead of raising. That way a failed API call comes back to the agent as readable text it can relay, rather than crashing the run.

Set up the client

Create a second file, weather_agent.py, for the agent itself. Start with the imports, configuration, and client. Keep weather_fn.py in the same directory, since you will upload it by path in a later step.

import os
import time

from seekrai import SeekrFlow
from seekrai.types.tools import CreateRunPython, RunPythonConfig
from seekrai.types.agents.agent import CreateAgentRequest

API_KEY = os.environ["SEEKR_API_KEY"]
API_URL = "https://flow.seekr.com/v1/"
MODEL_ID = "meta-llama/Llama-3.1-70B-Instruct"
FUNCTION_FILE = "weather_fn.py"
AGENT_NAME = "Weather Agent"
TOOL_NAME = "weather_tool"
FUNCTION_NAME = "get_current_weather"

client = SeekrFlow(api_key=API_KEY, base_url=API_URL)

This recipe uses meta-llama/Llama-3.1-70B-Instruct. A larger instruct model follows the “always call the tool” instruction reliably and handles the tool-calling handshake well. Any instruct model that supports tool calling works here, so you can substitute a smaller or newer model such as meta-llama/Llama-3.3-70B-Instruct to trade some quality for speed and cost.

Add two helper functions

These helpers wait for asynchronous operations to finish: one polls a run until it completes, and one polls the agent until it is Active after promotion. Add them to weather_agent.py.

def run_agent(agent_id: str, prompt: str, timeout: int = 300) -> str:
    thread = client.agents.threads.create()
    client.agents.threads.create_message(thread_id=thread.id, role="user", content=prompt)
    run_response = client.agents.runs.run(agent_id=agent_id, thread_id=thread.id, stream=False)

    deadline = time.time() + timeout
    while time.time() < deadline:
        run = client.agents.runs.retrieve(run_response.run_id, thread.id)
        if run.status.value == "completed":
            break
        if run.status.value in ("failed", "canceled"):
            raise RuntimeError(f"Run ended with status: {run.status.value}")
        time.sleep(3)
    else:
        raise TimeoutError(f"Run did not complete within {timeout}s.")

    messages = client.agents.threads.list_messages(thread.id, limit=10, order="desc")
    for msg in messages:
        if msg.role == "assistant":
            return msg.content if isinstance(msg.content, str) else str(msg.content)
    return "(no assistant message found)"


def promote_and_wait(agent_id: str, timeout: int = 120) -> None:
    client.agents.promote(agent_id)
    deadline = time.time() + timeout
    while time.time() < deadline:
        agent = client.agents.retrieve(agent_id)
        if agent.status.value == "Active":
            return
        if agent.status.value == "Failed":
            raise RuntimeError(f"Agent {agent_id} failed to deploy.")
        time.sleep(3)
    raise TimeoutError(f"Agent did not become Active within {timeout}s.")

Upload weather_fn.py so SeekrFlow can run it. The returned function ID connects your code to the tool in the next step.

fn = client.agents.custom_functions.create(file_path=FUNCTION_FILE)
print(f"Function registered: {fn.id!r}")

Create the run_python tool

Wrap the registered function in a run_python tool. The description is what the agent sees when it decides whether to call the tool, so make it specific.

tool = client.tools.create(
    CreateRunPython(
        name=TOOL_NAME,
        description="Fetches the current weather for ZIP code 22207 (Arlington, VA) from a live API.",
        config=RunPythonConfig(function_ids=[fn.id]),
    )
)
print(f"Tool created: {tool.id!r}")

Create the agent

Create the agent, attach the tool by ID, and give it instructions that tell it to always call the tool for weather questions.

agent = client.agents.create(
    CreateAgentRequest(
        name=AGENT_NAME,
        instructions=(
            "You are a weather assistant. Whenever the user asks about the weather, "
            "you MUST call the 'weather_tool' first and then report exactly what it returned."
        ),
        model_id=MODEL_ID,
        tool_ids=[tool.id],
    )
)
print(f"Agent created: {agent.id!r}")

Promote the agent

Promote the agent to deploy it, then wait for it to become Active.

promote_and_wait(agent.id)
print(f"'{AGENT_NAME}' is Active.")

Send a prompt

Send a prompt and print the agent’s reply. Because the instructions require it, the agent calls your function, which requests live data from wttr.in, and then reports the result.

response = run_agent(agent.id, "What's the weather like right now?")
print("\nAgent says:\n")
print(response)

Run the script

Run the finished script:

python weather_agent.py

You should see the agent report the current Arlington, VA forecast, sourced live from the weather API through your function.

Clean up resources (optional)

Promoted agents and their tools stay in your account until you remove them. When you are done experimenting, tear down the resources this recipe created. This deletes every agent, tool, and function that matches the names set at the top of weather_agent.py, so run it only against a scratch account.

for a in [a for a in client.agents.list_agents() if a.name == AGENT_NAME]:
    try:
        client.agents.demote(a.id)
    except Exception:
        pass
    client.agents.delete(a.id)
    print(f"Deleted agent: {a.id!r}")

for t in [t for t in client.tools.list().data if t.name == TOOL_NAME]:
    client.tools.delete(t.id)
    print(f"Deleted tool: {t.id!r}")

for f in [f for f in client.agents.custom_functions.list_functions() if f.name == FUNCTION_NAME]:
    client.agents.custom_functions.delete(f.id)
    print(f"Deleted function: {f.id!r}")

Next steps

Accept parameters. The function takes no arguments, so it always reports the same ZIP code. Add a zip_code: str parameter and describe it in the docstring so the agent can supply the location from the user’s question.
Call your own API. Swap the wttr.in request for a call to an internal service to give the agent access to your own live data.
Add more tools. Attach several functions to one agent and let it choose which to call based on the question.

​What you’ll build

​Prerequisites

​Build it

​Clean up resources (optional)

​Next steps

What you’ll build

Prerequisites

Build it

Clean up resources (optional)

Next steps