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

> What are agent payloads?

In Orkeia, the **AgentPayload** defines **how** you send a request to the agent at runtime.

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

### Table of Fields — `AgentPayload`

| Field    | Type                         | Required | Description                                                                | Example                                     |
| -------- | ---------------------------- | -------- | -------------------------------------------------------------------------- | ------------------------------------------- |
| agent    | string                       | Yes      | Identifier of the registered agent.                                        | "Suporte Orkeia"                            |
| input    | string                       | Yes      | User's prompt/message.                                                     | "Quais são os planos e valores?"            |
| context  | object, as per example below | No       | History of turns for continuity. Can alternate between user and assistant. | See example below                           |
| chatId   | string                       | No       | Conversation ID for persistence.                                           | "chat1234"                                  |
| files    | string                       | No       | URLs/paths of attachments.                                                 | "[www.arquivo.com](http://www.arquivo.com)" |
| metadata | Metadata                     | No       | Edge cache control.                                                        | see example below                           |

Example of context object:

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

Context example:

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

Metadata example:

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

### Table of Fields — `Metadata`

| Field      | Type    | Required | Description                       | Example |
| ---------- | ------- | -------- | --------------------------------- | ------- |
| useCache   | boolean | ✅        | If true, allows response reuse.   | true    |
| hoursCache | number  | ✅        | Cache validity window (in hours). | 6       |

### JSON Example — minimal call

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

### JSON Example — complete call (with history and 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
  }
}
```