Skip to content

Invocation contract

How callers reach an agent, and what the agent's server answers.

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.

Not available yet.

Not available yet.

Not available yet.

import { Sutra } from "@mistrive/sutra";

const sutra = new Sutra({
  baseUrl: "https://anchor.jgcp.mistrivedev.com",
});

const agent = await sutra.agents.get("support-bot");

// The first call with a new session id creates the session's sandbox.
// Later calls with the same id reach the same session.
const stream = agent.invoke({
  session: "user-42",
  input: { prompt: "Summarize the open issues." },
});

const decoder = new TextDecoder();
for await (const chunk of stream) {
  process.stdout.write(decoder.decode(chunk, { stream: true }));
}
import sys

from mistrive.sutra import Sutra

sutra = Sutra(
    base_url="https://anchor.jgcp.mistrivedev.com",
)

agent = sutra.agents.get("support-bot")

# The first call with a new session id creates the session's sandbox.
# Later calls with the same id reach the same session.
stream = agent.invoke(
    session="user-42",
    input={"prompt": "Summarize the open issues."},
)

for chunk in stream:
    sys.stdout.buffer.write(chunk)
    sys.stdout.flush()
#!/usr/bin/env bash
set -euo pipefail

# Assumes you ran `sutra auth login` (see the Quickstart).
# The first call with a new session id creates the session's sandbox.
# Later calls with the same id reach the same session.
sutra agents invoke support-bot \
  --session user-42 \
  --input '{"prompt": "Summarize the open issues."}'

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:

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:

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.

Type to search…

↑↓ navigate↵ selectEsc close