import json, os, httpx
with httpx.stream(
"POST", "https://api.onecortex.io/v1/agents/agt_.../invoke",
headers={"Authorization": f"Bearer {os.environ['ONECORTEX_API_KEY']}"},
json={"prompt": "hello", "stream": True},
) as response:
event = None
for line in response.iter_lines():
if line.startswith("event: "):
event = line[7:]
elif line.startswith("data: "):
data = json.loads(line[6:])
if event == "text":
print(data["delta"], end="", flush=True)
elif event == "tool_call_start":
print(f"[calling {data['name']}]")
elif event == "done":
print()
elif event == "error":
# Handle this, or a failure looks like an empty success.
raise RuntimeError(data["message"])
const response = await fetch('https://api.onecortex.io/v1/agents/agt_.../invoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ONECORTEX_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ prompt: 'hello', stream: true }),
})
const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''
while (true) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
// Frames are separated by a blank line. A partial frame stays buffered.
const frames = buffer.split('\n\n')
buffer = frames.pop() ?? ''
for (const frame of frames) {
const event = frame.match(/^event: (.*)$/m)?.[1]
const data = frame.match(/^data: (.*)$/m)?.[1]
if (!event || !data) continue
if (event === 'text') process.stdout.write(JSON.parse(data).delta)
if (event === 'tool_call_start') console.log(`[calling ${JSON.parse(data).name}]`)
if (event === 'done') console.log()
// Handle this, or a failure looks like an empty success.
if (event === 'error') throw new Error(JSON.parse(data).message)
}
}
curl -N https://api.onecortex.io/v1/agents/agt_.../invoke \
-H "Authorization: Bearer $ONECORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"hello","stream":true}'
{
"status": "completed",
"result": "<string>",
"events": [
{
"v": 1,
"type": "text",
"delta": "<string>"
}
],
"sessionId": "<string>",
"agentId": "<string>",
"versionNumber": 123,
"requestId": "<string>",
"durationMs": 123,
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"status": "completed",
"result": "<string>",
"events": [
{
"v": 1,
"type": "text",
"delta": "<string>"
}
],
"sessionId": "<string>",
"agentId": "<string>",
"versionNumber": 123,
"requestId": "<string>",
"durationMs": 123,
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}Invoke an agent
Send a prompt to a deployed agent. With stream true, or Accept: text/event-stream, the response is a stream of server sent events, one per event, ending in exactly one done or error. Otherwise it is one JSON body once the run is over.
A stream that has started has sent 200 OK and cannot change it: a failure after that arrives as event: error. Handle it.
Every field beyond prompt, sessionId, stream and messages reaches the agent unchanged, as params.
import json, os, httpx
with httpx.stream(
"POST", "https://api.onecortex.io/v1/agents/agt_.../invoke",
headers={"Authorization": f"Bearer {os.environ['ONECORTEX_API_KEY']}"},
json={"prompt": "hello", "stream": True},
) as response:
event = None
for line in response.iter_lines():
if line.startswith("event: "):
event = line[7:]
elif line.startswith("data: "):
data = json.loads(line[6:])
if event == "text":
print(data["delta"], end="", flush=True)
elif event == "tool_call_start":
print(f"[calling {data['name']}]")
elif event == "done":
print()
elif event == "error":
# Handle this, or a failure looks like an empty success.
raise RuntimeError(data["message"])
const response = await fetch('https://api.onecortex.io/v1/agents/agt_.../invoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ONECORTEX_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ prompt: 'hello', stream: true }),
})
const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''
while (true) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
// Frames are separated by a blank line. A partial frame stays buffered.
const frames = buffer.split('\n\n')
buffer = frames.pop() ?? ''
for (const frame of frames) {
const event = frame.match(/^event: (.*)$/m)?.[1]
const data = frame.match(/^data: (.*)$/m)?.[1]
if (!event || !data) continue
if (event === 'text') process.stdout.write(JSON.parse(data).delta)
if (event === 'tool_call_start') console.log(`[calling ${JSON.parse(data).name}]`)
if (event === 'done') console.log()
// Handle this, or a failure looks like an empty success.
if (event === 'error') throw new Error(JSON.parse(data).message)
}
}
curl -N https://api.onecortex.io/v1/agents/agt_.../invoke \
-H "Authorization: Bearer $ONECORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"hello","stream":true}'
{
"status": "completed",
"result": "<string>",
"events": [
{
"v": 1,
"type": "text",
"delta": "<string>"
}
],
"sessionId": "<string>",
"agentId": "<string>",
"versionNumber": 123,
"requestId": "<string>",
"durationMs": 123,
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}{
"status": "completed",
"result": "<string>",
"events": [
{
"v": 1,
"type": "text",
"delta": "<string>"
}
],
"sessionId": "<string>",
"agentId": "<string>",
"versionNumber": 123,
"requestId": "<string>",
"durationMs": 123,
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}Authorizations
An Onecortex API key, oc_live_..., from API keys in the dashboard.
Path Parameters
The agent's ID, from its page in the dashboard.
"agt_01K0000000000000000000000"
Body
At most 1 MB. Any other field reaches the agent unchanged, as params.
The input to the agent.
Your key for a conversation. Calls with the same one reach the same running instance. Generated when absent.
1 - 256True for server sent events. Absent, the Accept header decides.
The conversation as you hold it, for an agent that reads history.
Show child attributes
Show child attributes
Anything the agent should see, at most 4 KB as JSON. Reaches the agent in params.
Response
The run completed. JSON, or a stream of events.
completed, failed The whole reply. On a failed run, the text sent before it failed.
The tool calls, tool results and steps, in order. Text is in result.
One event of a run. Every event carries v, which is 1, and type.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
Show child attributes
Show child attributes
Present when status is failed.
Show child attributes
Show child attributes