> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seekr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage agents

> Create, configure, and manage agents using the SeekrFlow Python SDK.

An agent must be active before it can process requests. Create and promote your agent using the operations below, then see [Run an agent](/flow/sdk/agents/run-an-agent) to start processing requests.

## Create an agent

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

| Parameter          | Description                                                                                                                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | **Required.** A string that identifies your agent.                                                                                                                                                                |
| `instructions`     | Also known as a developer message or system prompt. Guides how the agent operates and generates its response.                                                                                                     |
| `model_id`         | The model used to generate the agent's response. Can be a base model or fine-tuned model.                                                                                                                         |
| `tool_ids`         | IDs of the tools the agent can use. Create the tools in the [tool library](/flow/sdk/agents/tools) first, then provide their IDs.                                                                                 |
| `reasoning_effort` | How much reasoning the agent uses when working through a request. Accepts `LOW`, `MEDIUM`, or `HIGH`. Defaults to `MEDIUM`.                                                                                       |
| `temperature`      | **Optional.** 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`](/flow/reference/create_v1_flow_agents_create_post)

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

<Info>
  The model that generates an agent's response can be any base or fine-tuned model available on the SeekrFlow platform.
</Info>

For details on agent status, see [Agent status](/flow/components/agents#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`.

| Level                    | Description                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `ReasoningEffort.LOW`    | Prioritizes speed. Best for simple, latency-sensitive tasks with a small tool set.                                   |
| `ReasoningEffort.MEDIUM` | Balances speed and thoroughness. A good starting point for most use cases.                                           |
| `ReasoningEffort.HIGH`   | Prioritizes 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.

<Note>
  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`.
</Note>

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.

| Parameter             | Description                                                                                                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `output.instructions` | Instructions for generating the final response. When set, the top-level `instructions` guide only the agent's reasoning, and these guide the response.                              |
| `output.model_id`     | The model used to generate the final response, overriding the top-level `model_id`. Can be a base model or fine-tuned model.                                                        |
| `output.temperature`  | Controls the predictability of the final response. Accepts a value from `0` to `2`. Defaults to `0.6`.                                                                              |
| `output.frequency`    | When 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. |

<CodeGroup>
  ```python Python theme={null}
  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,
          ),
      )
  )
  ```
</CodeGroup>

<Note>
  You must provide either `model_id` or `output.model_id`.
</Note>

## 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/`](/flow/reference/list_agents_v1_flow_agents__get)

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

## 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}`](/flow/reference/patch_v1_flow_agents__agent_id__patch)

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

| Parameter          | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `name`             | Updated agent name.                                   |
| `instructions`     | Updated system prompt.                                |
| `tool_ids`         | Updated list of tool IDs. Replaces the existing list. |
| `model_id`         | Updated response model.                               |
| `reasoning_effort` | Updated reasoning effort.                             |
| `temperature`      | Updated temperature.                                  |
| `output`           | Updated output configuration.                         |

<Note>
  Agents in `Inactive` or `Failed` states remain in their current state after an update. To activate an updated agent, [promote it](/flow/reference/promote_v1_flow_agents__agent_id__promote_put) manually.
</Note>

### 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`](/flow/reference/diff_v1_flow_agents__agent_id__diff_patch)

<CodeGroup>
  ```python Python theme={null}
  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)
  ```
</CodeGroup>

The response includes the complete before and after agent state, and a `diff` object identifying each changed field:

<CodeGroup>
  ```python Python theme={null}
  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."
          }
      }
  )
  ```
</CodeGroup>

## Promote an agent

<Info>
  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.
</Info>

**Endpoint:** [`PUT /v1/flow/agents/{agent_id}/promote`](/flow/reference/promote_v1_flow_agents__agent_id__promote_put)

<CodeGroup>
  ```python Python theme={null}
  agent = client.agents.promote(agent.id)
  print(f"Agent promoted. Agent ID: {agent.id}")
  ```
</CodeGroup>

When promoting an agent that has [sub-agents linked as tools](/flow/sdk/agents/agent-as-tool), 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`](/flow/reference/demote_v1_flow_agents__agent_id__demote_put)

<CodeGroup>
  ```python Python theme={null}
  agent = client.agents.demote(agent.id)
  print(f"Agent demoted. Agent ID: {agent.id}")
  ```
</CodeGroup>

<Note>
  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](/flow/sdk/agents/agent-as-tool) for details.
</Note>

## Delete an agent

This permanently removes an agent from the SeekrFlow platform.

**Endpoint:** [`DELETE /v1/flow/agents/{agent_id}`](/flow/reference/delete_v1_flow_agents__agent_id__delete)

<CodeGroup>
  ```python Python theme={null}
  del_response = client.agents.delete(agent.id)
  print(f"Agent deleted. Agent ID: {agent.id}")
  ```
</CodeGroup>

<Note>
  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](/flow/sdk/agents/agent-as-tool).
</Note>