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

> ¿Qué son los payloads de agentes?

En Orkeia, el **AgentPayload** define **cómo** envías una solicitud al agente en tiempo de ejecución.

```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;
}
```

### Tabla de campos — `AgentPayload`

| Campo    | Tipo                        | Obligatorio | Descripción                                                                    | Ejemplo                                     |
| -------- | --------------------------- | ----------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
| agent    | string                      | Sí          | Identificador del agente registrado.                                           | "Soporte Orkeia"                            |
| input    | string                      | Sí          | Prompt/mensaje del usuario                                                     | "¿Cuáles son los planes y valores?"         |
| context  | objeto, según ejemplo abajo | No          | Historial de turnos para continuidad. Puede alternar entre usuario y asistente | Véase ejemplo abajo                         |
| chatId   | string                      | No          | ID de la conversación para persistencia                                        | "chat1234"                                  |
| files    | string                      | No          | URLs/paths de archivos adjuntos                                                | "[www.archivo.com](http://www.archivo.com)" |
| metadata | Metadata                    | No          | Control de caché en el borde                                                   | véase ejemplo abajo                         |

Ejemplo de objeto de context:

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

Ejemplo de context:

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

Ejemplo de Metadata

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

### Tabla de campos — `Metadata`

| Campo      | Tipo    | Obligatorio | Descripción                                       | Ejemplo |
| ---------- | ------- | ----------- | ------------------------------------------------- | ------- |
| useCache   | boolean | ✅           | Si es verdadero, permite reutilizar la respuesta. | true    |
| hoursCache | number  | ✅           | Ventana de validez del caché (en horas).          | 6       |

### Ejemplo JSON — llamada mínima

```json theme={null}
{
  "agent": "Soporte Orkeia",
  "input": "Necesito ayuda con la factura"
}
```

### Ejemplo JSON — llamada completa (con histórico y caché)

```json theme={null}
{
  "agent": "Soporte Orkeia",
  "input": "¿Cuáles son los planes y valores?",
  "context": [
    { "role": "user", "content": "¡Hola!" },
    { "role": "assistant", "content": "¡Hola! ¿Cómo puedo ayudar?" }
  ],
  "chatId": "chat_12345",
  "files": ["https://storage.orkeia.ai/docs/termos.pdf"],
  "metadata": {
    "useCache": true,
    "hoursCache": 12
  }
}
```