1# Invocations Protocol Guide
2 
3The `invocations` protocol is **bytes in, bytes out**. The platform is pure pass-through — the raw HTTP request body is forwarded to the container and the raw response is returned. The agent developer defines what the container accepts and returns. Unlike `responses` (OpenAI-compatible with platform-managed history), `invocations` gives full control to the container code.
4 
5## Input/Output Contract
6 
7| Aspect | `responses` | `invocations` |
8|--------|------------|---------------|
9| **Input** | `inputText` is a natural language message (e.g., `"What is the weather?"`) | `inputText` is forwarded as the **raw HTTP request body** — bytes in. Format as whatever the container's invoke handler expects (typically JSON) |
10| **Output** | Structured OpenAI response with `output_text` | **Raw response bytes** from the container — JSON, text, or SSE events. Format is defined by the agent developer |
11| **Conversation history** | Platform-managed via `conversationId` | Agent-managed via session filesystem; `conversationId` does **not** apply |
12| **Streaming** | Platform-managed via `stream: true` | Agent-controlled; `stream` parameter does **not** apply |
13 
14## Discovering the Expected Input Schema
15 
16> ⚠️ **Do not guess the invocations request body.** The developer defines the schema in the container's invoke handler. The platform does not validate or transform the payload.
17 
18### 1. Fetch the OpenAPI Spec (Preferred)
19 
20Agents can register an OpenAPI spec that describes the expected request/response format. Fetch it from:
21 
22```text
23GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/invocations/docs/openapi.json
24```
25 
26If the developer registered an `openapi_spec` when creating the server, this returns the full API contract. If not registered, it returns 404.
27 
28### 2. Inspect Agent Source Code
29 
30Look at the agent's invoke handler — the function registered with `@app.invoke_handler` (Python) or equivalent. The handler reads the raw request (e.g., `request.json()` for JSON, `request.body()` for raw bytes) and returns a `Response`.
31 
32### 3. Ask the User
33 
34If neither the OpenAPI spec nor source code is available, ask the user for the expected request body format before invoking.
35 
36## Examples
37 
38**Responses protocol** (default):
39 
40```text
41agent_invoke(projectEndpoint, agentName, inputText: "What is the weather in Seattle?")
42→ Structured response with output_text
43```
44 
45**Invocations protocol** — agent expects `{"message": "<text>"}`:
46 
47```text
48agent_invoke(projectEndpoint, agentName, inputText: "{\"message\":\"hello\"}", protocol: "invocations", sessionId: "<session-id>")
49→ Raw bytes from container, e.g.: {"response": "Hi there!", "session_id": "abc123"}
50```
51 
52## Common Use Cases
53 
54| Scenario | Why Invocations |
55|----------|----------------|
56| Webhook receiver (GitHub, Stripe, Jira) | External system sends its own payload format |
57| Non-conversational processing (classification, extraction) | Input is structured data, not a chat message |
58| Custom streaming protocol (AG-UI) | Needs raw SSE control, not OpenAI-compatible streaming |
59| Protocol bridge (proprietary systems) | Caller has its own protocol that doesn't map to `/responses` |
60 
61## Error Handling
62 
63| Error | Cause | Resolution |
64|-------|-------|------------|
65| 400/422 or invocation failed | Request body does not match what the container expects | Fetch OpenAPI spec or inspect handler code for the correct schema |
66| 404 on OpenAPI spec | Developer did not register an `openapi_spec` | Inspect handler source code or ask the user for the API contract |
67| Empty response | Agent returned no content | Check agent logs via `session_logstream`; verify the handler processes the request body correctly |
68