---
title: "Invocation contract"
description: "How callers reach an agent, and what the agent's server answers."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.jgcp.mistrivedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invocation contract

:::note[Planned]
Invoking an agent over its host is not available yet. The samples show the planned API.
:::

The contract has two sides: callers send requests to the agent's host, and your code in the session's sandbox answers them.

## Call an agent

A caller sends `POST {agent host}/invocations` with the session id in a header. The SDK and CLI set the header for you. The request needs your API key or a signed link.

The response streams. Sutra passes your server's response through as it is written, so callers see output as soon as your agent produces it.

## Serve the contract

Set the revision's `protocol` to say which contract your code serves.

### HTTP

With `protocol: "HTTP"`, your server listens on port 8080 and answers two routes:

| Route | What it does |
| --- | --- |
| `POST /invocations` | Takes the request body and returns or streams the response. |
| `GET /ping` | Reports health: `{"status": "Healthy"}`, or `{"status": "HealthyBusy"}` while it is still working. |

The contract is compatible with Amazon Bedrock AgentCore, so a server written for AgentCore runs unchanged.

A session counts as idle when no request is in flight. If your agent keeps working after it responds, for example on a background task, answer `HealthyBusy` from `/ping`. That keeps the session from stopping until the work is done.

A minimal server in TypeScript:

```ts
import { createServer } from "node:http";

let busy = false;

createServer(async (req, res) => {
  if (req.method === "GET" && req.url === "/ping") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ status: busy ? "HealthyBusy" : "Healthy" }));
    return;
  }
  if (req.method === "POST" && req.url === "/invocations") {
    let body = "";
    for await (const chunk of req) body += chunk;
    const { prompt } = JSON.parse(body);
    res.writeHead(200, { "Content-Type": "text/plain" });
    for (const word of `You said: ${prompt}`.split(" ")) res.write(`${word} `);
    res.end();
    return;
  }
  res.writeHead(404).end();
}).listen(8080, "0.0.0.0");
```

The same server in Python:

```python
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != "/ping":
            return self.send_error(404)
        body = json.dumps({"status": "Healthy"}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

    def do_POST(self):
        if self.path != "/invocations":
            return self.send_error(404)
        length = int(self.headers["Content-Length"])
        prompt = json.loads(self.rfile.read(length))["prompt"]
        self.send_response(200)
        self.send_header("Content-Type", "text/plain")
        self.end_headers()
        for word in f"You said: {prompt}".split():
            self.wfile.write(f"{word} ".encode())
            self.wfile.flush()


ThreadingHTTPServer(("0.0.0.0", 8080), Handler).serve_forever()
```

### MCP

With `protocol: "MCP"`, your code serves the Model Context Protocol instead. Callers connect to the agent's host with an MCP client and use your tools and prompts. Sessions work the same way as over HTTP.

Source: https://docs.jgcp.mistrivedev.com/agents/invocation/index.mdx
