> ## 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:

`name`: A required string that identifies your agent.

`instructions`: Also known as a developer message or system prompt. Guides how the agent plans its actions and generates its response.

`model_id`: Which LLM to use as the base model.

`tool_ids`: IDs of the tools the agent can use. Create tools in the [tool library](/flow/sdk/agents/tools) first, then reference them here.

**Endpoint:** `POST /v1/flow/agents/create` [Create agent](/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.SPEED_OPTIMIZED

      )
  )
  print(f"Agent created with ID: {agent.id}")
  print(f"Agent status: {agent.status}")
  ```
</CodeGroup>

<Info>
  Agents can be configured to use 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

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:

**Endpoint:** `GET /v1/flow/agents/` [List 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}` [Update agent](/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 base model.                                   |
| `reasoning_effort`    | Updated reasoning effort.                             |
| `planner_temperature` | Updated planner temperature.                          |

<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` [Preview agent update](/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` [Promote agent](/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` [Demote agent](/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}` [Delete agent](/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>