Skip to main content

Quickstart

Use the OpenAI SDK to create an agent and a session, submit a task, and receive results through SSE.

Prerequisites

  1. Activate Model Studio and create an API Key.
  2. Install Python 3.9 or later.
  3. Confirm a model available in the workspace, for example qwen3.8-max.
pip install openai requests
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export BASE_URL="https://{workspace_id}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
Replace {workspace_id} with the actual workspace ID.
The examples use environment.type=none. This does not create a sandbox and does not provide built-in tools such as shell or file access. To use files, commands, or environment-side MCP, create a managed environment as described in Environment.

1. Create an agent

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url=os.environ["BASE_URL"],
)

agent = client.beta.agents.create(
    model="qwen3.8-max",
    name="quickstart-agent",
    instructions="Answer briefly and include only necessary information.",
)
print(agent.id)

2. Create a session and receive streamed output

session_id = None
stream = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Introduce yourself in one sentence.",
    stream=True,
)

for event in stream:
    if event.type == "agent.session.created":
        session_id = event.session.id
        print(f"Session: {session_id}")
    elif event.type == "agent.session.turn.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "agent.session.idle":
        print()
        break

print(f"Session ID: {session_id}")
HTTP 201 means the session and the first input were accepted. It does not mean execution has completed. Use agent.session.idle or the turn terminal status to determine completion.

3. Query history

turns = client.beta.agents.sessions.turns.list(
    session_id,
    limit=20,
    order="asc",
)
for turn in turns.data:
    print(turn.id, turn.status)
    items = client.beta.agents.sessions.turns.items.list(
        turn.id,
        session_id=session_id,
        limit=100,
        order="asc",
    )
    for item in items.data:
        print(item.type, item.id)

4. Continue the session

with client.beta.agents.sessions.stream(
    session_id,
    input="Add one more sentence.",
) as stream:
    for event in stream:
        if event.type == "agent.session.turn.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "agent.session.idle":
            print()
            break
Confirm that the session is idle before continuing. sessions.stream subscribes to events, submits the input, and receives the result for this turn. A message sent while the session is running usually steers the current turn; if the turn ends before consuming the input, the message can be delivered in a new turn, so track ownership by the actual events and turn ID.

5. Use curl

Create an agent:
curl -sS -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "name": "quickstart-agent",
    "instructions": "Answer briefly and include only necessary information."
  }'
Create a session:
curl -N -sS -X POST "$BASE_URL/agents/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xxx",
    "environment": {"type": "none"},
    "input": "Introduce yourself in one sentence.",
    "stream": true
  }'
stream: true returns the first-turn SSE directly in the create response, so a fast reply is not missed by subscribing after creation. To subscribe to an existing session, use GET /agents/sessions/{session_id}/events; that subscription does not replay historical events.

6. Clean up

client.beta.agents.sessions.delete(session_id)
client.beta.agents.delete(agent.id)
Deleting a session stops its execution and removes public history. Deleting an agent affects only new sessions; existing sessions keep their snapshot.