Start Agent

POST /start_agent

Start Agent

cURL

curl --request POST \
  --url https://api.gumloop.com/api/v1/start_agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "gummie_id": "<string>",
  "message": "<string>",
  "user_id": "<string>",
  "project_id": "<string>",
  "interaction_id": "<string>"
}
'

200

{
  "interaction_id": "<string>",
  "status": "<string>"
}

Send a message to a Gumloop agent and start an asynchronous interaction. Returns immediately with an interaction_id that you use to poll for results.

To continue an existing conversation, pass the interaction_id from a previous run. The new message is appended to that conversation’s history and the same interaction_id is reused. See Continuing a Conversation below.

Request

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Body Parameters

gummie_id · string · required

The unique identifier of the agent to trigger. See Finding Your Agent ID below.

message · string · required

The message/prompt to send to the agent. This is a natural language string, not structured inputs.

user_id · string

Your Gumloop user ID. Required if project_id is not provided.

project_id · string

Your team (workspace) ID. Required if user_id is not provided. Can be combined with user_id.

interaction_id · string

The interaction_id from a previous completed or failed interaction. When provided, the new message is appended to the existing conversation and the same interaction_id is reused. The previous interaction must be in a terminal state (COMPLETED or FAILED).

Example Request

cURL

curl -X POST https://api.gumloop.com/api/v1/start_agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "gummie_id": "abc123DEFghiJKL",
    "message": "Summarize the latest sales report and send it to the team Slack channel",
    "user_id": "your_user_id",
    "project_id": "your_project_id"
  }'

Response

Success (202 Accepted)

interaction_id · string

Unique identifier for this interaction. Use this to poll for results via the Retrieve Agent Status endpoint.

status · string

Always "processing" on success, indicating the agent has started working.

{
  "interaction_id": "xYz789AbCdEfGhI",
  "status": "processing"
}

Error Responses

Status Code	Error	Description
400	"gummie_id is required"	Missing gummie_id in the request body.
400	"message is required"	Missing message in the request body.
400	"project_id or user_id is required"	Missing both project_id and user_id.
401	"Authorization header with Bearer token or api_key query parameter is required"	No API key provided.
403	"Unauthorized"	Invalid API key.
403	"unauthorized_gummie_access"	User doesn’t have permission to access this agent.
403	"unauthorized_interaction_access"	User doesn’t have permission to access the specified interaction (continuation only).
404	"gummie_not_found"	No agent found with the provided gummie_id.
404	"interaction_not_found"	No interaction found with the provided interaction_id (continuation only).
400	"interaction_gummie_mismatch"	The interaction_id belongs to a different agent than the specified gummie_id (continuation only).
409	"interaction_not_in_terminal_state"	The interaction is still processing and cannot be continued yet. Wait until it reaches COMPLETED or FAILED (continuation only).

---

Finding Your Agent ID

The gummie_id is the unique identifier for your Gumloop agent. You can find it from the URL when viewing your agent:

https://www.gumloop.com/agents/{gummie_id}

For example, if your URL is https://www.gumloop.com/agents/abc123DEFghiJKL, then your gummie_id is abc123DEFghiJKL.

You can also find the agent ID on the agent’s settings/configuration page in the Gumloop app.

---

Complete Workflow

After starting an agent interaction, poll for results:

1. POST /api/v1/start_agent
   → Send: gummie_id, message, user_id (+ optional project_id)
   → Receive: interaction_id, status: "processing"

2. GET /api/v1/agent_status/{interaction_id}  (poll repeatedly)
   → While state == "ASYNC_PROCESSING": wait and poll again
   → When state == "COMPLETED": read response and/or messages
   → When state == "FAILED": read error_message

See the Retrieve Agent Status endpoint for full details on polling and response schemas.

---

Continuing a Conversation

To continue an existing conversation, include the interaction_id from a previous run in your request body. The agent receives the full prior message history plus your new message, so it can respond with awareness of the earlier context.

Requirements

• The previous interaction must be in a terminal state (COMPLETED or FAILED)
• The gummie_id must match the agent that owns the interaction
• The caller must have access to the interaction

Continuation Flow

1. POST /api/v1/start_agent  (initial request)
   → Send: gummie_id, message, user_id
   → Receive: interaction_id, status: "processing"

2. GET /api/v1/agent_status/{interaction_id}  (poll until COMPLETED)

3. POST /api/v1/start_agent  (follow-up request)
   → Send: gummie_id, message, user_id, interaction_id (from step 1)
   → Receive: same interaction_id, status: "processing"

4. GET /api/v1/agent_status/{interaction_id}  (poll until COMPLETED)
   → Messages now include the full conversation thread

Example: Multi-Turn Conversation

Python

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://api.gumloop.com/api/v1"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

def send_message(gummie_id: str, message: str, user_id: str, interaction_id: str = None) -> dict:
    """Send a message to an agent, optionally continuing an existing conversation."""
    payload = {
        "gummie_id": gummie_id,
        "message": message,
        "user_id": user_id,
    }
    if interaction_id:
        payload["interaction_id"] = interaction_id

    response = requests.post(f"{BASE_URL}/start_agent", headers=HEADERS, json=payload)
    response.raise_for_status()
    return response.json()

def wait_for_completion(interaction_id: str, user_id: str) -> dict:
    """Poll until the interaction completes or fails."""
    while True:
        response = requests.get(
            f"{BASE_URL}/agent_status/{interaction_id}",
            headers=HEADERS,
            params={"user_id": user_id}
        )
        response.raise_for_status()
        result = response.json()

        if result["state"] == "COMPLETED":
            return result
        elif result["state"] == "FAILED":
            raise RuntimeError(f"Agent failed: {result.get('error_message')}")
        time.sleep(2)

# Turn 1: Start a new conversation
start = send_message(
    gummie_id="abc123DEFghiJKL",
    message="Find all open support tickets from Acme Corp",
    user_id="your_user_id"
)
interaction_id = start["interaction_id"]
result = wait_for_completion(interaction_id, "your_user_id")
print(f"Turn 1: {result['response']}")

# Turn 2: Continue the conversation
send_message(
    gummie_id="abc123DEFghiJKL",
    message="Now draft a summary email to send to the account manager",
    user_id="your_user_id",
    interaction_id=interaction_id  # reuse the same interaction
)
result = wait_for_completion(interaction_id, "your_user_id")
print(f"Turn 2: {result['response']}")

---

Full Example: Start and Poll

Python

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://api.gumloop.com/api/v1"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

def trigger_agent(gummie_id: str, message: str, user_id: str, project_id: str = None) -> dict:
    """
    Trigger a Gumloop agent and wait for the response.

    Args:
        gummie_id: The agent's unique ID
        message: The message to send to the agent
        user_id: Your Gumloop user ID
        project_id: Optional team/workspace ID

    Returns:
        dict with 'response' (agent's text reply) and 'messages' (full conversation)
    """
    # Step 1: Start the agent interaction
    payload = {
        "gummie_id": gummie_id,
        "message": message,
        "user_id": user_id,
    }
    if project_id:
        payload["project_id"] = project_id

    start_response = requests.post(
        f"{BASE_URL}/start_agent",
        headers=HEADERS,
        json=payload
    )
    start_response.raise_for_status()
    interaction_id = start_response.json()["interaction_id"]
    print(f"Started agent interaction: {interaction_id}")

    # Step 2: Poll for completion
    params = {"user_id": user_id}
    if project_id:
        params["project_id"] = project_id

    while True:
        status_response = requests.get(
            f"{BASE_URL}/agent_status/{interaction_id}",
            headers=HEADERS,
            params=params
        )
        status_response.raise_for_status()
        result = status_response.json()

        state = result["state"]
        if state == "COMPLETED":
            print(f"Agent response: {result['response']}")
            return result
        elif state == "FAILED":
            error_msg = result.get("error_message", "Unknown error")
            raise RuntimeError(f"Agent interaction failed: {error_msg}")
        else:
            # Still processing -- wait and poll again
            time.sleep(2)


# Usage
result = trigger_agent(
    gummie_id="abc123DEFghiJKL",
    message="Summarize the Q4 sales report",
    user_id="your_user_id",
    project_id="your_project_id"  # optional
)

print(result["response"])      # The agent's final text response
print(result["messages"])       # Full conversation with tool call details

---

Authentication Notes

• You can use either a Personal API Key or a Team API Key. See Authentication for details.
• If you authenticate with a personal API key and pass both user_id and project_id, the system verifies you are a member of the specified team before allowing the request.
• The agent uses the credentials associated with the user_id and project_id provided in the request.

The Python and JavaScript SDKs do not yet support agent triggering. Use the raw HTTP examples above until SDK support is added.