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

# AgentPayload

> O que são os payloads de agentes?

No Orkeia, o **AgentPayload** define **como** você envia uma requisição ao agente em tempo de execução.

```typescript theme={null}

export interface AgentPayload {
  agent: string;
  input: string;
  context?: { role: 'user' | 'assistant'; content: string }[];
  chatId?: string;
  files?: string[];
  metadata?: Metadata;
}

export interface Metadata {
  useCache: boolean;
  hoursCache: number;
}
```

### Tabela de campos — `AgentPayload`

| Campo    | Tipo                            | Obrigatório | Descrição                                                                          | Exemplo                                     |
| -------- | ------------------------------- | ----------- | ---------------------------------------------------------------------------------- | ------------------------------------------- |
| agent    | string                          | Sim         | Identificador do agente cadastrado.                                                | "Suporte Orkeia"                            |
| input    | string                          | Sim         | Prompt/mensagem do usuário                                                         | "Quais são os planos e valores?"            |
| context  | objeto, conforme exemplo abaixo | Não         | Histórico de turnos para continuidade. Podendo alternar entre usuario e assistente | Vide exemplo abaixo                         |
| chatId   | string                          | Não         | ID da conversa para persistência                                                   | "chat1234"                                  |
| files    | string                          | Não         | URLs/paths de anexos                                                               | "[www.arquivo.com](http://www.arquivo.com)" |
| metadata | Metadata                        | Não         | Controle de cache na borda                                                         | vide exemplo abaixo                         |

Exemplo de objeto de context:

```typescript theme={null}
context: { 
	role: 'user' | 'assistant';
	content: string;
}[]
```

Exemplo de context:

```json theme={null}
[
	{
		"role":"user",
		"content":"oi"
	}
]
```

Exemplo de Metadata

```json theme={null}
{
	"useCache": true, "hoursCache": 6} 
```

### Tabela de campos — `Metadata`

| Campo      | Tipo    | Obrigatório | Descrição                                 | Exemplo |
| ---------- | ------- | ----------- | ----------------------------------------- | ------- |
| useCache   | boolean | ✅           | Se verdadeiro, permite reuso de resposta. | true    |
| hoursCache | number  | ✅           | Janela de validade do cache (em horas).   | 6       |

### Exemplo JSON — chamada mínima

```json theme={null}
{
  "agent": "Suporte Orkeia",
  "input": "Preciso de ajuda com a fatura"
}
```

### Exemplo JSON — chamada completa (com histórico e cache)

```json theme={null}
{
  "agent": "Suporte Orkeia",
  "input": "Quais são os planos e valores?",
  "context": [
    { "role": "user", "content": "Olá!" },
    { "role": "assistant", "content": "Oi! Como posso ajudar?" }
  ],
  "chatId": "chat_12345",
  "files": ["https://storage.orkeia.ai/docs/termos.pdf"],
  "metadata": {
    "useCache": true,
    "hoursCache": 12
  }
}
```