Skip to main content

​
Invoke with Session

Invoke an agent with context from a session.

​
Request Body

​
agent
string
required
Agent deployment slug
​
prompt
string
required
User message / task
​
session
string
Session ID for context. If omitted, creates ephemeral invocation.
​
context
object
Context selection options
​
enrichment
string
Enrichment mode: none, manual, auto
​
enrichmentConfig
object
Enrichment configuration
​
stream
boolean
default:"false"
Enable streaming response
​
saveToSession
boolean
default:"true"
Save conversation to session
curl -X POST https://api.runtools.ai/v1/aip/invoke \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Continue the auth implementation we discussed",
    "session": "sess_abc123",
    "context": {
      "includeByTag": ["authentication"],
      "maxTokens": 50000
    },
    "enrichment": "auto",
    "stream": true
  }'

{
  "data": {
    "id": "inv_abc123",
    "status": "completed",
    "output": "I've continued the auth implementation...",
    "agent": "code-assistant",
    "session": "sess_abc123",
    "blocksCreated": ["blk_new001", "blk_new002"],
    "usage": {
      "contextTokens": 45000,
      "inputTokens": 46200,
      "outputTokens": 1850
    }
  }
}

​
Streaming Response

When stream: true, response is Server-Sent Events: 
event: start
data: {"invocationId": "inv_abc123", "agent": "code-assistant"}

event: context_assembled
data: {"tokenCount": 45000, "blocksIncluded": 12}

event: thinking
data: {"content": "Looking at the auth implementation..."}

event: text_delta
data: {"content": "Based on our previous discussion"}

event: text_delta
data: {"content": " about JWT tokens, I'll continue..."}

event: tool_call
data: {"tool": "edit_file", "input": {"path": "/src/auth.ts"}}

event: tool_result
data: {"output": "File updated"}

event: complete
data: {"output": "Done!", "blocksCreated": ["blk_new001"], "usage": {...}}

​
Event Types

EventDescription
startInvocation started
context_assembledContext selected and assembled
thinkingAgent thinking/reasoning
text_deltaText chunk
tool_callTool being called
tool_resultTool execution result
file_editFile was edited
dev_urlDev server URL available
completeInvocation finished
errorError occurred

​
AIP-Compatible Endpoint

Standard AIP protocol endpoint for cross-platform compatibility.

​
Headers

​
X-AIP-Agent
string
required
Agent deployment slug

​
Request Body

Same as /v1/aip/invoke but follows AIP specification format: 
{
  "aip_version": "0.1.0",
  "prompt": {
    "content": "Build a landing page",
    "attachments": []
  },
  "context": {
    "session_id": "sess_abc123",
    "include_by_tag": ["relevant"]
  },
  "options": {
    "stream": true,
    "save_to_session": true
  }
}

curl -X POST https://api.runtools.ai/.well-known/aip/invoke \
  -H "X-API-Key: rt_live_xxx" \
  -H "X-AIP-Agent: code-assistant" \
  -H "Content-Type: application/json" \
  -d '{
    "aip_version": "0.1.0",
    "prompt": { "content": "Build a landing page" },
    "context": { "session_id": "sess_abc123" }
  }'
The /.well-known/aip/invoke endpoint follows the open AIP specification for interoperability with other AIP-compatible platforms.