Poetry contest with a supervisor agent

SeekrFlow lets you expose one agent to another as a tool. This recipe uses that pattern to build a small multi-agent system: a supervisor agent coordinates two specialist sub-agents, a limerick writer and a haiku writer. The supervisor sends the user’s prompt to each sub-agent, collects both poems, and declares a winner. The pattern is the useful part. Once a sub-agent is a tool, the supervisor decides when to call it the same way it would call any other tool, so you can compose focused agents into a larger workflow instead of building one agent that tries to do everything.

What you’ll build

A supervisor agent that:

Wraps a Limerick Agent and a Haiku Agent as agent_as_tool tools.
Sends the user’s prompt to both sub-agents.
Presents both poems, clearly labeled.
Picks a favorite and explains why.

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

Set up the client

Create agents_as_tools.py and start with the imports, configuration, and client.

import os
import time

from seekrai import SeekrFlow
from seekrai.types.tools import CreateAgentAsTool, AgentAsToolConfig
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"
TEST_PROMPT = "My cat refuses to get off my keyboard while I'm trying to work."

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

This recipe uses meta-llama/Llama-3.1-70B-Instruct. The supervisor has to call both sub-agent tools and then reason over their output, so a capable instruct model with reliable tool calling matters more here than in a single-tool agent. Any instruct model that supports tool calling works, such as meta-llama/Llama-3.3-70B-Instruct.

Add helper functions

These helpers wait for asynchronous operations and make the script safe to run more than once. run_agent polls a run to completion, promote_and_wait polls an agent until it is Active, and the get_or_create helpers reuse existing resources instead of creating duplicates.

def run_agent(agent_id: str, prompt: str, timeout: int = 300) -> str:
    """Start a run, poll until complete, then return the assistant's reply."""
    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:
    """Promote an agent and poll until it's Active."""
    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.")


def get_or_create_agent(request: CreateAgentRequest):
    """Return an existing agent with the same name, or create a new one."""
    existing = next((a for a in client.agents.list_agents() if a.name == request.name), None)
    if existing:
        print(f"  Found existing '{existing.name}': {existing.id!r}")
        return existing
    agent = client.agents.create(request)
    print(f"  Created '{agent.name}': {agent.id!r}")
    return agent


def get_or_create_tool(request: CreateAgentAsTool):
    """Return an existing agent_as_tool with the same name, or create a new one."""
    existing = next((t for t in client.tools.list().data if t.name == request.name), None)
    if existing:
        print(f"  Found existing tool '{existing.name}': {existing.id!r}")
        return existing
    tool = client.tools.create(request)
    print(f"  Created tool '{tool.name}': {tool.id!r}")
    return tool


def ensure_active(agent) -> None:
    """Promote the agent only if it isn't already Active."""
    if agent.status.value == "Active":
        print(f"  '{agent.name}' is already Active.")
        return
    print(f"  Promoting '{agent.name}'...")
    promote_and_wait(agent.id)
    print(f"  '{agent.name}' is Active.")

Create the sub-agents

Create the two specialist agents. Each has narrow instructions that keep it focused on a single job.

limerick_agent = get_or_create_agent(CreateAgentRequest(
    name="Limerick Agent",
    instructions=(
        "You are the Limerick Agent. Whatever prompt the user sends you, "
        "respond ONLY with a creative limerick about it. "
        "Do not add any other commentary."
    ),
    model_id=MODEL_ID,
))

haiku_agent = get_or_create_agent(CreateAgentRequest(
    name="Haiku Agent",
    instructions=(
        "You are the Haiku Agent. Whatever prompt the user sends you, "
        "respond ONLY with a haiku (5-7-5 syllables) about it. "
        "Do not add any other commentary."
    ),
    model_id=MODEL_ID,
))

Promote the sub-agents

A sub-agent must be Active before it can be wrapped as a tool, so promote both now.

ensure_active(limerick_agent)
ensure_active(haiku_agent)

Wrap each sub-agent as a tool

Create an agent_as_tool tool for each sub-agent. The description is what the supervisor sees when it decides which tool to call, and the config points at the sub-agent by ID.

limerick_tool = get_or_create_tool(CreateAgentAsTool(
    name="limerick_agent",
    description="Sends a prompt to the Limerick Agent and returns a limerick.",
    config=AgentAsToolConfig(agent_id=limerick_agent.id),
))

haiku_tool = get_or_create_tool(CreateAgentAsTool(
    name="haiku_agent",
    description="Sends a prompt to the Haiku Agent and returns a haiku.",
    config=AgentAsToolConfig(agent_id=haiku_agent.id),
))

Create the supervisor

Create the supervisor agent and attach both tools. Its instructions tell it to call each tool and then compare the results.

supervisor = get_or_create_agent(CreateAgentRequest(
    name="Supervisor Agent",
    instructions=(
        "You are a supervisor. When the user gives you a prompt:\n"
        "1. Send it verbatim to the 'limerick_agent' tool and note its output.\n"
        "2. Send it verbatim to the 'haiku_agent' tool and note its output.\n"
        "3. Present BOTH outputs to the user, clearly labelled.\n"
        "4. Declare which one you personally like more, and briefly explain why."
    ),
    tool_ids=[limerick_tool.id, haiku_tool.id],
    model_id=MODEL_ID,
))

ensure_active(supervisor)

Send a prompt

Send a prompt to the supervisor and print its reply. The supervisor calls both sub-agents, then returns both poems with its verdict.

response = run_agent(supervisor.id, TEST_PROMPT)
print("Supervisor says:\n")
print(response)

Run the script

Run the finished script:

python agents_as_tools.py

You should see a limerick and a haiku about the prompt, followed by the supervisor’s pick.

Clean up resources (optional)

Promoted agents and their tools stay in your account until you remove them. When you are done, add this helper and call it to tear down everything the recipe created.

def cleanup(*agent_ids, tool_ids=()):
    for agent_id in agent_ids:
        try:
            client.agents.demote(agent_id)
            client.agents.delete(agent_id)
            print(f"  Deleted agent {agent_id!r}")
        except Exception as e:
            print(f"  Warning: could not delete agent {agent_id!r}: {e}")
    for tool_id in tool_ids:
        try:
            client.tools.delete(tool_id)
            print(f"  Deleted tool {tool_id!r}")
        except Exception as e:
            print(f"  Warning: could not delete tool {tool_id!r}: {e}")


cleanup(
    supervisor.id, limerick_agent.id, haiku_agent.id,
    tool_ids=(limerick_tool.id, haiku_tool.id),
)

Next steps

Add more specialists. Wrap additional sub-agents (a sonnet writer, a translator) as tools and attach them to the supervisor.
Route instead of fan out. Change the supervisor’s instructions so it picks the single best sub-agent for a prompt rather than calling all of them.
Nest deeper. A sub-agent can have tools of its own, including other agents, so you can build multi-level workflows.

​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