Agents Overview

An agent is a configuration object that defines the tools, instructions, and model settings - it's not a running process but rather a blueprint or template. The actual execution of tasks happens separately when you invoke this agent configuration, keeping the definition distinct from its runtime behavior. Think of an agent as a recipe that specifies ingredients and instructions: the recipe itself doesn't cook the meal, but it provides all the necessary information for someone (or something) to execute the cooking process when needed.

Creating an Agent

The most common properties of an agent you'll configure are:

name: A required string that identifies your agent.instructions: Also known as a developer message or system prompt. These are the guiding instructions for your agentmodel: which LLM to use as base modeltools: Tools that the agent can use to achieve its tasks.

from seekrai.types import CreateAgentRequest
from seekrai import SeekrFlow
api_key = "your_api_key"
client = SeekrFlow(api_key=api_key)

agent = client.agents.create(
    CreateAgentRequest(
        name="homework_tutor_bot",
        instructions="You are a tutor bot for middle schoolers. Answers the questions in a way middle schoolers can understand",
        model_id="meta-llama/Llama-3.1-8B-Instruct",
        tools=[], 
				reasoning_effort=ReasoningEffort.SPEED_OPTIMIZED

    )
)
print(f"Agent created with ID: {agent.id}")
print(f"Agent status: {agent.status}")

Note: Agents can be configured to use any base or fine-tuned model available on the SeekrFlow platform.

Instructions Best Practices

When formulating the agent's instruction's we suggest the following best practices:

1. Define Role, Goal, and Context
   Clearly state the agent’s persona, objective, and any relevant background.

“You are a procurement research assistant tasked with finding active government contracts based on user input.”

2. Be Specific and Prescriptive
   Break complex tasks into simpler, step-by-step subgoals, and ensure the instruction includes how each tool is to be leveraged.

"Use the search_contracts tool only after collecting both a state and keyword.”

3. Call Out Edge Cases and Desired Behavior Explicitly
   If the agent should not respond to certain queries or behaviors, say so directly.

“Do not answer legal or compliance questions — respond with: ‘I’m not able to help with that.’”

4. Output Guidelines
   If not using structured outputs, be extremely clear about the desired format and tone.

“Respond in a numbered list with no more than 3 items. Use plain language and avoid technical jargon.”

Agent Status

Each agent has an associated status.

• Active indicates the agent is ready to serve active traffic
• Pending indicates the agent has recently been promoted and will soon become active
• Inactive indicates the agent is not currently deployed, and needs to be activated before it can service traffic

Agent Reasoning

SeekrFlow agents support two distinct reasoning modes, each optimized for different use cases and performance requirements. The reasoning effort level determines how the agent processes information, plans its actions, and selects appropriate tools to accomplish tasks.

• ReasoningEffort.SPEED_OPTIMIZED: Designed for low-latency applications, this mode uses streamlined reasoning processes that consume fewer computational resources while generating the agent's execution plan. This approach prioritizes quick response times and is ideal for scenarios where immediate feedback is critical and the agent has access to a limited set of tools.
• ReasoningEffort.PERFORMANCE_OPTIMIZED: Built for complex scenarios requiring deeper analytical processing, this mode employs enhanced reasoning capabilities to handle intricate decision-making and tool selection. This approach is essential for agents managing multiple tools or executing sophisticated workflows where accuracy and thoroughness outweigh response speed considerations.

We recommend experimenting with both reasoning modes during agent development to determine the optimal configuration for your specific use case. Generally, SPEED_OPTIMIZED performs well for latency-sensitive applications with simple tool sets, while PERFORMANCE_OPTIMIZED is necessary for agents utilizing extensive tool arrays to ensure consistent, reliable results.

List Your Agents and Their Status

To list all of the agent's you've created and their associated status, you can use the below code snippet:

available_agents = client.agents.list_agents()

print("Available agents:")
for agent in available_agents:
    print(f"ID: {agent.id}, Name: {agent.name}, Status: {agent.status}"

Promote an agent

Note: Agent create requests will promote an agent automatically. Agents only need to be promoted after they've been demoted and are in an inactive state.

agent = client.agents.promote(agent.id)
print(f"Agent promoted. Agent ID: {agent.id}")

Demote an agent

Demoting an agent moves it to an inactive state. This is useful when you want to retain the agent's definition without allowing it to handle inference requests.

agent = client.agents.demote(agent.id)
print(f"Agent demoted. Agent ID: {agent.id}")

Delete an agent

This permanently removes an agent from the SeekrFlow platform.

del_response = client.agents.delete(agent.id)
print(f"Agent deleted. Agent ID: {agent.id}")