AgentPayload - Orkeia AI

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

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”
metadata	Metadata	No	Edge cache control.	see example below

Example of context object:

context: { 
	role: 'user' | 'assistant';
	content: string;
}[]

Context example:

[
	{
		"role":"user",
		"content":"oi"
	}
]

Metadata example:

{
	"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

{
  "agent": "Suporte Orkeia",
  "input": "Preciso de ajuda com a fatura"
}

JSON Example — complete call (with history and cache)

{
  "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
  }
}