Skip to main content
An agent must be active before it can process requests. Create and promote your agent using the operations below, then see Run an agent to start processing requests.

​
Create an agent

The most common properties of an agent you’ll configure are:
ParameterDescription
nameRequired. A string that identifies your agent.
instructionsAlso known as a developer message or system prompt. Guides how the agent operates and generates its response.
model_idThe model used to generate the agent’s response. Can be a base model or fine-tuned model.
tool_idsIDs of the tools the agent can use. Create the tools in the tool library first, then provide their IDs.
reasoning_effortHow much reasoning the agent uses when working through a request. Accepts LOW, MEDIUM, or HIGH. Defaults to MEDIUM.
temperatureOptional. Controls the predictability of the agent’s reasoning. Lower values produce more consistent results, and higher values introduce more variation. Accepts a value from 0 to 2. Defaults to 0.6.
Endpoint: POST /v1/flow/agents/create 
from seekrai.types import CreateAgentRequest, ReasoningEffort
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.3-70B-Instruct",
        tool_ids=[],
        reasoning_effort=ReasoningEffort.MEDIUM,
        temperature=0.6
    )
)
print(f"Agent created with ID: {agent.id}")
print(f"Agent status: {agent.status}")
The model that generates an agent’s response can be any base or fine-tuned model available on the SeekrFlow platform.
For details on agent status, see Agent status.

​
Write effective instructions

When writing your agent’s instructions, follow these best practices:
  1. Define role, goal, and context. Clearly state the agent’s persona, objective, and any relevant background. Example: “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 subgoals and specify how each tool should be used. Example: “Use the search_contracts tool only after collecting both a state and keyword.”
  3. Call out edge cases explicitly. If the agent should not respond to certain queries, say so directly. Example: “Do not answer legal or compliance questions — respond with: ‘I’m not able to help with that.’”
  4. Specify output format. If not using structured outputs, be clear about the desired format and tone. Example: “Respond in a numbered list with no more than 3 items. Use plain language and avoid technical jargon.”

​
Configure reasoning effort

The reasoning_effort level determines how much reasoning the agent uses to process information, decide how to approach the task, and select appropriate tools. SeekrFlow agents support three levels. The default is MEDIUM.
LevelDescription
ReasoningEffort.LOWPrioritizes speed. Best for simple, latency-sensitive tasks with a small tool set.
ReasoningEffort.MEDIUMBalances speed and thoroughness. A good starting point for most use cases.
ReasoningEffort.HIGHPrioritizes thoroughness. Best for complex workflows with many tools where accuracy matters more than response time.
We recommend experimenting with different levels during agent development to find the optimal configuration for your use case.
The SPEED_OPTIMIZED and PERFORMANCE_OPTIMIZED values are only supported for backward compatibility. Use LOW, MEDIUM, or HIGH for new agents. SPEED_OPTIMIZED corresponds to LOW, and PERFORMANCE_OPTIMIZED to HIGH.
To adjust how predictable or varied the agent’s reasoning is, set temperature (a value from 0 to 2, default 0.6). Lower values produce more consistent results, and higher values introduce more variation.

​
Configure output settings

By default, an agent produces a natural-language response using the same instructions, model_id, and temperature that guide its reasoning. To control the response separately, provide an output configuration. All of its fields are optional.
ParameterDescription
output.instructionsInstructions for generating the final response. When set, the top-level instructions guide only the agent’s reasoning, and these guide the response.
output.model_idThe model used to generate the final response, overriding the top-level model_id. Can be a base model or fine-tuned model.
output.temperatureControls the predictability of the final response. Accepts a value from 0 to 2. Defaults to 0.6.
output.frequencyWhen the agent produces a written response: ALWAYS, AUTOMATIC (the agent decides), or NEVER. Use NEVER for automation cases where a natural-language response isn’t needed.
from seekrai.types import CreateAgentRequest, AgentOutputConfig, AgentOutputFrequency

agent = client.agents.create(
    CreateAgentRequest(
        name="research_assistant",
        instructions="Work through the user's question using the available tools.",
        model_id="meta-llama/Llama-3.3-70B-Instruct",
        tool_ids=[],
        output=AgentOutputConfig(
            instructions="Summarize the findings in a concise, professional tone.",
            temperature=0.4,
            frequency=AgentOutputFrequency.AUTOMATIC,
        ),
    )
)
You must provide either model_id or output.model_id.

​
List your agents and their status

To list all of the agents you’ve created and their associated status, you can use the below code snippet: Endpoint: GET /v1/flow/agents/ 
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}")

​
Update an agent

Use agents.update to make partial changes to an existing agent. Provide only the fields you want to change. Omitted fields remain unchanged. Endpoint: PATCH /v1/flow/agents/{agent_id} 
from seekrai.types import UpdateAgentRequest

updated_agent = client.agents.update(
    agent_id=agent.id,
    request=UpdateAgentRequest(
        instructions="You are a tutor bot for high schoolers. Answer questions in a way high schoolers can understand."
    )
)
print(f"Agent updated: {updated_agent.id}")
ParameterDescription
nameUpdated agent name.
instructionsUpdated system prompt.
tool_idsUpdated list of tool IDs. Replaces the existing list.
model_idUpdated response model.
reasoning_effortUpdated reasoning effort.
temperatureUpdated temperature.
outputUpdated output configuration.
Agents in Inactive or Failed states remain in their current state after an update. To activate an updated agent, promote it manually.

​
Preview an agent update

Use agents.update_diff to simulate an update without applying it. The response shows exactly what would change. Endpoint: PATCH /v1/flow/agents/{agent_id}/diff 
from seekrai.types import UpdateAgentRequest

diff = client.agents.update_diff(
    agent_id=agent.id,
    request=UpdateAgentRequest(
        name="homework_tutor_bot_v2",
        instructions="You are a tutor bot for high schoolers."
    )
)
print(diff)
The response includes the complete before and after agent state, and a diff object identifying each changed field: 
AgentDiffResponse(
    before=...,
    after=...,
    diff={
        "name": {
            "before": "homework_tutor_bot",
            "after": "homework_tutor_bot_v2"
        },
        "instructions": {
            "before": "You are a tutor bot for middle schoolers...",
            "after": "You are a tutor bot for high schoolers."
        }
    }
)

​
Promote an agent

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.
Endpoint: PUT /v1/flow/agents/{agent_id}/promote 
agent = client.agents.promote(agent.id)
print(f"Agent promoted. Agent ID: {agent.id}")
When promoting an agent that has sub-agents linked as tools, SeekrFlow automatically promotes the sub-agents first. The supervisor remains in Pending state until all sub-agents are ready.

​
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. Endpoint: PUT /v1/flow/agents/{agent_id}/demote 
agent = client.agents.demote(agent.id)
print(f"Agent demoted. Agent ID: {agent.id}")
Demoting a supervisor does not automatically demote its sub-agents. Each sub-agent must be demoted individually if needed. A sub-agent cannot be demoted while it is still linked to an active supervisor—demote the supervisor first, or unlink the sub-agent. See Agent as tool for details.

​
Delete an agent

This permanently removes an agent from the SeekrFlow platform. Endpoint: DELETE /v1/flow/agents/{agent_id} 
del_response = client.agents.delete(agent.id)
print(f"Agent deleted. Agent ID: {agent.id}")
Deleting a supervisor does not affect its sub-agents or their agent-as-tool wrappers. To delete a sub-agent, first unlink it from any supervisors and delete its associated agent-as-tool.
Last modified on July 8, 2026