Gram Agents API usage examples

The following examples demonstrate different ways to use the Gram Agents API. All examples use the API endpoint at https://app.getgram.ai/rpc/agents.response.

Basic request

A simple synchronous request with a single toolset:

import os
import requests

url = "https://app.getgram.ai/rpc/agents.response"

headers = {
    "Content-Type": "application/json",
    "Gram-Key": os.getenv("GRAM_API_KEY"),
    "Gram-Project": "default",
}

payload = {
    "model": "openai/gpt-4o",
    "instructions": "You are a helpful assistant.",
    "input": "What information can you retrieve about my account?",
    "toolsets": [
        {
            "toolset_slug": "my-api",
            "environment_slug": "my-env",
            "headers": {}
        },
    ],
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data["output"][-1]["content"][-1]["text"])

Multiple toolsets

Combine multiple toolsets in a single request to give the agent access to different APIs:

payload = {
    "model": "openai/gpt-4o",
    "instructions": "You are a helpful assistant with access to multiple services.",
    "input": "Find the user's email and look up their payment history.",
    "toolsets": [
        {
            "toolset_slug": "user-api",
            "environment_slug": "my-env",
            "headers": {}
        },
        {
            "toolset_slug": "payments-api",
            "environment_slug": "my-env",
            "headers": {}
        },
    ],
}

Sub-agents

Define specialized sub-agents for complex workflows. Each sub-agent can have its own toolsets and instructions:

payload = {
    "model": "openai/gpt-4o",
    "async": True,
    "instructions": "You are a coordinator that delegates tasks to specialized agents.",
    "input": "Get user details and their payment history, then summarize.",
    "sub_agents": [
        {
            "name": "User Agent",
            "description": "Handles user-related operations.",
            "instructions": "Fetch user information using the provided tools.",
            "toolsets": [
                {
                    "toolset_slug": "user-api",
                    "environment_slug": "my-env",
                    "headers": {}
                },
            ]
        },
        {
            "name": "Payments Agent",
            "description": "Handles payment-related operations.",
            "tools": [
                "tools:http:payments:get_charges",
                "tools:http:payments:get_refunds",
            ],
            "environment_slug": "my-env",
        },
    ],
}

Sub-agents can be configured with either:

• toolsets: Full toolset references
• tools: Specific tool URNs for fine-grained control

Asynchronous execution

For longer-running tasks, use async mode and poll for results:

import os
import time
import requests

url = "https://app.getgram.ai/rpc/agents.response"

headers = {
    "Content-Type": "application/json",
    "Gram-Key": os.getenv("GRAM_API_KEY"),
    "Gram-Project": "default",
}

payload = {
    "model": "openai/gpt-4o",
    "async": True,
    "instructions": "You are a helpful assistant.",
    "input": "Analyze the data and provide a summary.",
    "toolsets": [
        {
            "toolset_slug": "analytics-api",
            "environment_slug": "my-env",
            "headers": {}
        },
    ],
}

# Start the async request
response = requests.post(url, headers=headers, json=payload)
data = response.json()
response_id = data["id"]

print(f"Response ID: {response_id}")

# Poll for completion
poll_url = f"https://app.getgram.ai/rpc/agents.response?response_id={response_id}"

while True:
    time.sleep(5)
    poll_response = requests.get(poll_url, headers=headers)
    poll_data = poll_response.json()
    status = poll_data.get("status")

    print(f"Status: {status}")

    if status != "in_progress":
        print(poll_data["output"][-1]["content"][-1]["text"])
        break

Multi-turn conversations with previous_response_id

Chain responses together using previous_response_id to build conversational agents:

import os
import requests

url = "https://app.getgram.ai/rpc/agents.response"

headers = {
    "Content-Type": "application/json",
    "Gram-Key": os.getenv("GRAM_API_KEY"),
    "Gram-Project": "default",
}

payload = {
    "model": "openai/gpt-4o",
    "instructions": "You are a helpful assistant.",
    "input": "Get the details of organization 'acme-corp'.",
    "toolsets": [
        {
            "toolset_slug": "org-api",
            "environment_slug": "my-env",
            "headers": {}
        },
    ],
}

# First turn
response = requests.post(url, headers=headers, json=payload)
data = response.json()

print("Turn 1:", data["output"][-1]["content"][-1]["text"])

# Second turn - reference the previous response
payload["previous_response_id"] = data["id"]
payload["input"] = "What workspaces are in that organization?"

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print("Turn 2:", data["output"][-1]["content"][-1]["text"])

Multi-turn conversations with message history

Alternatively, pass the full conversation history in the input field:

# First turn
payload = {
    "model": "openai/gpt-4o",
    "instructions": "You are a helpful assistant.",
    "input": [
        {"role": "user", "content": "Get the details of organization 'acme-corp'."}
    ],
    "toolsets": [
        {
            "toolset_slug": "org-api",
            "environment_slug": "my-env",
            "headers": {}
        },
    ],
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

# Second turn - include previous output in context
payload["input"] = [
    *data["output"],
    {"role": "user", "content": "What workspaces are in that organization?"}
]

response = requests.post(url, headers=headers, json=payload)

Disable response storage

Use store: false to prevent the response from being saved:

payload = {
    "model": "openai/gpt-4o",
    "instructions": "You are a helpful assistant.",
    "input": "Process this sensitive request.",
    "store": False,
    "toolsets": [
        {
            "toolset_slug": "my-api",
            "environment_slug": "my-env",
            "headers": {}
        },
    ],
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

# Response is available immediately but will be deleted shortly after
print(data["output"][-1]["content"][-1]["text"])

Note that store: false requires synchronous execution (async: false or omitted).

More examples

Additional examples are available in the Gram examples repository.