Skip to main content
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

FieldTypeRequiredDescriptionExample
agentstringYesIdentifier of the registered agent.”Suporte Orkeia”
inputstringYesUser’s prompt/message.”Quais são os planos e valores?“
contextobject, as per example belowNoHistory of turns for continuity. Can alternate between user and assistant.See example below
chatIdstringNoConversation ID for persistence.”chat1234”
filesstringNoURLs/paths of attachments.”www.arquivo.com”
metadataMetadataNoEdge 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

FieldTypeRequiredDescriptionExample
useCacheboolean✅If true, allows response reuse.true
hoursCachenumber✅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
  }
}