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

# Atualizar Fluxo do Agente

> Atualizar o modo de conversação e a configuração de fluxo de um agente

# Atualizar Fluxo do Agente

Atualiza o modo de conversação de um agente e (quando aplicável) a configuração estruturada do fluxo. Submeter um fluxo inválido retorna um 422 com detalhes — use [Validar Fluxo do Agente](/api-reference/endpoints/validate-agent-flow) para executar a validação em modo de teste antes de salvar.

## Endpoint

```
PUT /api/v1/agents/{agent_id}/flow
```

## Parâmetros de caminho

<ParamField path="agent_id" type="string" required>UUID do agente.</ParamField>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Deve ser definido como `application/json`
</ParamField>

## Corpo da requisição

<ParamField body="conversation_mode" type="string" required>
  Modo de conversação. Opções:

  * `llm_driven` — conversa guiada por LLM (conhecimento + ações). Envie `flow_config: null` ou omita.
  * `flow_driven` — guiado por grafo de nós. `flow_config` é obrigatório.
</ParamField>

<ParamField body="flow_config" type="object">
  Definição do fluxo. Obrigatório quando `conversation_mode` é `flow_driven`.

  <Expandable title="objeto flow_config">
    <ParamField body="initial_node_id" type="string" required>
      ID do nó de entrada. Deve referenciar um nó existente em `nodes`.
    </ParamField>

    <ParamField body="meta" type="object">
      Metadados opcionais: `{ "name": "string", "version": "string" }`.
    </ParamField>

    <ParamField body="nodes" type="array" required>
      Array de objetos de nó. Cada nó tem no mínimo: `id` (string, único), `type` (`say`, `ask`, `decision`, `action`, `transfer`, `end`), e campos específicos do tipo (`content`, `next`, `branches`, etc.).
    </ParamField>

    <ParamField body="global_functions" type="array">
      Funções invocáveis a partir de qualquer nó. Entradas comuns: `end_conversation`, `transfer_call`, `repeat_question`.
    </ParamField>
  </Expandable>
</ParamField>

## Exemplos

<RequestExample>
  ```bash theme={null}
  # Mudar para o modo llm_driven
  curl -X PUT "https://app.talkover.ai/api/v1/agents/agent-uuid/flow" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{ "conversation_mode": "llm_driven" }'
  ```

  ```bash theme={null}
  # Definir uma configuração flow-driven
  curl -X PUT "https://app.talkover.ai/api/v1/agents/agent-uuid/flow" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation_mode": "flow_driven",
      "flow_config": {
        "initial_node_id": "node-greet",
        "meta": { "name": "Intake v1", "version": "1.0.0" },
        "nodes": [
          { "id": "node-greet", "type": "say", "content": "Hi!", "next": "node-end" },
          { "id": "node-end", "type": "end" }
        ],
        "global_functions": [
          { "name": "end_conversation", "description": "Ends the call" }
        ]
      }
    }'
  ```
</RequestExample>

## Resposta

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "conversation_mode": "flow_driven",
      "flow_config": { . }
    }
  }
  ```
</ResponseExample>

## Respostas de erro

### 422 — Fluxo Inválido

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Flow validation failed",
    "errors": [
      "initial_node_id 'node-greet' not found in nodes",
      "Node 'node-qualify' references unknown next node 'node-bookx'"
    ]
  }
  ```
</ResponseExample>

## Observações

* Atualizar o fluxo não altera o status do agente — mas agentes publicados precisam ser republicados se a alteração no fluxo for incompatível (breaking).
* Veja [Listar Versões do Fluxo](/api-reference/endpoints/list-agent-flow-versions) para acompanhar configurações históricas.