Skip to content

Python Quickstart

This quickstart walks you through four practical tasks using the SCRAPI Python API — from listing your Apps all the way to running an evaluation. Each task builds on the last, so by the end you'll have a solid feel for how the library hangs together.

Prerequisites

Before you start, make sure you have:

  • SCRAPI installed: pip install cxas-scrapi
  • Authentication configured (see Authentication)
  • A GCP project with at least one CX Agent Studio App

You'll need your GCP project ID and the location of your App. Locations are typically us, global, or a regional identifier like us-central1.

Task 1 — List your Apps

An "App" is the top-level container in CX Agent Studio. Let's start by listing all the Apps in your project:

from cxas_scrapi import Apps

# Replace with your GCP project ID and location
PROJECT_ID = "my-gcp-project"
LOCATION = "us"

# Create the Apps client
app_client = Apps(project_id=PROJECT_ID, location=LOCATION)

# List all Apps in the project
apps = app_client.list_apps()

for app in apps:
    print(f"App: {app.display_name}")
    print(f"  Resource name: {app.name}")
    print()

What you'll see:

App: My Customer Service Bot
  Resource name: projects/my-gcp-project/locations/us/apps/abc123

App: Internal HR Assistant
  Resource name: projects/my-gcp-project/locations/us/apps/def456

The app.name field — that long resource name — is what SCRAPI calls the app_name. You'll use it to identify your App when working with Agents, Tools, Evaluations, and other resources. Copy it — you'll need it in the tasks below.

Using get_apps_map()

list_apps() returns raw API objects. If you prefer a simple dictionary keyed by display name, use app_client.get_apps_map() instead.

Task 2 — List Agents in an App

Each App contains one or more Agents. Let's see what's inside your App:

from cxas_scrapi import Agents

# Use the full resource name from Task 1
APP_NAME = "projects/my-gcp-project/locations/us/apps/abc123"

agent_client = Agents(app_name=APP_NAME)

# List all Agents in the App
agents = agent_client.list_agents()

for agent in agents:
    print(f"Agent: {agent.display_name}")
    print(f"  Resource name: {agent.name}")
    print()

What you'll see:

Agent: Main Playbook Agent
  Resource name: projects/my-gcp-project/locations/us/apps/abc123/agents/agent-001

Agent: Escalation Handler
  Resource name: projects/my-gcp-project/locations/us/apps/abc123/agents/agent-002

One App, many Agents

A single App typically has one main Agent (handling the primary conversation) and may have additional Agents for specific workflows, escalations, or specialized tasks. See Key Concepts for more detail.

Task 3 — Send a test message

Now let's interact with an agent by sending it a message. The Sessions class manages conversations:

from cxas_scrapi import Sessions

APP_NAME = "projects/my-gcp-project/locations/us/apps/abc123"

session_client = Sessions(app_name=APP_NAME)

# Create a new session (a unique conversation thread)
session_id = session_client.create_session_id()
print(f"Session ID: {session_id}")

# Send a message to the agent
response = session_client.run(
    session_id=session_id,
    text="Hello! What can you help me with today?",
)

# Print the agent's response
session_client.parse_result(response)

What you'll see:

Session ID: 550e8400-e29b-41d4-a716-446655440000
AGENT RESPONSE: Hi there! I can help you with account inquiries, billing questions, ...

Think of a session as a single conversation thread — like a chat window. Each time you call run with the same session_id, the agent remembers the context from earlier in that conversation.

Generating session IDs

create_session_id() generates a UUID for you. You can also provide your own string — just make sure it's unique per conversation.

Task 4 — Run an evaluation

Evaluations let you systematically test your agent's behavior. Here's how to run a simple tool evaluation — which checks that your agent's tools return the values you expect:

from cxas_scrapi import ToolEvals

APP_NAME = "projects/my-gcp-project/locations/us/apps/abc123"

# Initialize the ToolEvals client
tool_evals = ToolEvals(app_name=APP_NAME)

# Load test cases from a YAML file
test_cases = tool_evals.load_tool_test_cases_from_file("evals/tool_tests/order_tests.yaml")

# Run the tests — returns a pandas DataFrame
results_df = tool_evals.run_tool_tests(test_cases)

# Print results
print(results_df[["test_name", "tool", "status"]].to_string())

The YAML test file format looks like this:

tests:
  - name: check_order_status_returns_data
    tool: check_order_status
    args:
      order_id: "ORD-12345"

What you'll see:

Running test: check_order_status_returns_data (check_order_status)
PASSED: check_order_status --> check_order_status_returns_data

Five evaluation types

SCRAPI supports five evaluation types: ToolEvals, CallbackEvals, SimulationEvals, GuardrailEvals, and TurnEvals. Each one tests a different aspect of your agent's behavior. See the Evaluation Guide for a full walkthrough.

Putting it all together

Here's a simple script that combines all four tasks:

from cxas_scrapi import Apps, Agents, Sessions

PROJECT_ID = "my-gcp-project"
LOCATION = "us"

# 1. Find your App
app_client = Apps(project_id=PROJECT_ID, location=LOCATION)
apps = app_client.list_apps()
my_app = apps[0]  # Take the first one for this example
print(f"Using App: {my_app.display_name}")

app_name = my_app.name

# 2. List its Agents
agent_client = Agents(app_name=app_name)
agents = agent_client.list_agents()
print(f"Found {len(agents)} agent(s)")

# 3. Send a test message
session_client = Sessions(app_name=app_name)
session_id = session_client.create_session_id()

response = session_client.run(
    session_id=session_id,
    text="Hello!",
)
session_client.parse_result(response)

What's next?

You've covered the basics! Here are some good next steps: