​
Overview

Clients call through the SGP API to Agent Service in order to CRUD agent configs and execute agents. Agent configs are stored in Agents DB, together with the internal run states of the agents. The service also talks to secrets vault (e.g. AWS secrets manager) and blob store (e.g. AWS S3). For SGP native assets like knowledge bases and LLMs the service also talks back to the SGP API.

​
Creating Agent Configurations

  1. Create an Application Specification
    • Generates a timestamp.
    • Sends a POST request to create an application spec (/v4/application-specs).
    • Extracts the application_spec_id from the response.
# Create application spec
timestamp = int(time.time())

response = await c.post(
    "/v4/application-specs",
    **TEST_USER_AUTH,
    json={
        "name": f"Loop {timestamp}",
        "description": "Agentic Application",
        "account_id": ACCOUNT_ID,
    },
)
application_spec_id = response.json()["id"]
  1. Load YAML Configuration
    • Reads a YAML config file (loop_with_list_demo.yaml).
    • Assigns a unique ID (uuid4()) and associates an account_id.
    • Determines the agent type (STATE_MACHINE, PLAN, or WORKFLOW) based on YAML contents.
# Load agent yaml config
filepath = "../../examples/tutorial/05-loops/loop_with_list_demo.yaml"
filename = Path(filepath).name

with open(filepath) as f:
    config = yaml.safe_load(f)
    config["id"] = str(uuid4())
    config["account_id"] = ACCOUNT_ID
    agent_type = (
        "STATE_MACHINE" if "machine" in config else "PLAN" if "plan" in config else "WORKFLOW"
    )
  1. Construct and Send Application Variant Request
    • Builds a JSON payload with the application variant details.
    • Sends a POST request to /v4/application-variants to create a variant.
    • Extracts the variant_id from the response.
# Construct application variant config payload
json_data = {
    "name": f"{filename} variant",
    "description": f"{filename} app variant description",
    "configuration": {
        "params": config,
        "type": agent_type,
    },
    "version": "AGENTS_SERVICE",
    "application_spec_id": application_spec_id,
    "account_id": ACCOUNT_ID,
}

print(json_data)

# Create agentic application variant
response = await c.post(
    "/v4/application-variants",
    **TEST_USER_AUTH,
    json=json_data,
)

variant_id = response.json()["id"]

​
Executing an Agent

You can send a POST request to an agent variant as a standard request or stream the response line by line.

  1. Process a Variant (Standard Request)
    • Sends a POST request to process a specific application variant.
    • Provides input parameters (object: "tree") for processing.
    • Returns a JSON response containing the processed result.
# Process variant
response = await c.post(
    f"/v4/applications/{variant_id}/process",
    **TEST_USER_AUTH,
    json={
        "inputs": {
            "object": "tree",
        },
    },
)

response.json()
  1. Stream Responses from the Variant
    • Sends a POST request with stream=True to enable real-time streaming.
    • Asynchronously processes and prints incoming data as it arrives.
# Stream variant
async with c.stream(
    "POST",
    f"/v4/applications/{variant_id}/process",
    **TEST_USER_AUTH,
    json={
        "inputs": {
            "object": "tree",
        },
        "stream": True,
    },
) as response:
    # Ensure the response is OK
    response.raise_for_status()

    # Stream the response line by line
    async for line in response.aiter_text():
        if line.startswith("data:"):
            data = line.lstrip("data: ").strip()
            print(f"Received data: {data}")
        elif line.startswith("event:"):
            event = line.lstrip("event: ").strip()
            print(f"Received event: {event}")
Running Agents in SGPHow to Run an Evaluation