REST-API-Referenz für die BMA-Vorschau

In dieser Referenz werden die in den Vorschaubeispielen verwendeten Sitzungs-, Ereignis- und Elementoperationen beschrieben. Verwenden Sie eine AWS SigV4-signed Anfrage an den regionalen bedrock-mantle Endpunkt. Der Signaturdienst istbedrock-mantle.

Operationen

Operation	Methode und Pfad	Erfolgreiche Antwort
Erstellen einer Sitzung	POST /openai/v1/agents/sessions	Ressource für die Sitzung
Sitzungen auflisten	GET /openai/v1/agents/sessions	Paginierte Sitzungsliste
Rufen Sie eine Sitzung ab	GET /openai/v1/agents/sessions/{session_id}	Sitzungsressource
Eine Sitzung löschen	DELETE /openai/v1/agents/sessions/{session_id}	Bestätigung des Löschvorgangs
Eingabeereignisse einreichen	POST /openai/v1/agents/sessions/{session_id}/events	Annahmebestätigung; der Text kann leer sein
Ereignisse streamen	GET /openai/v1/agents/sessions/{session_id}/events	text/event-stream
Artikel auflisten	GET /openai/v1/agents/sessions/{session_id}/items	Paginierte Artikelliste

Verwenden Sie die vom Dienst zurückgegebenen IDs. Behandeln Sie Sitzungs-IDs, Umgebungs-IDs, Turn-IDs und Paginierungscursor als undurchsichtige Werte.

Erstellen einer Sitzung

Anforderung

POST /openai/v1/agents/sessions
Content-Type: application/json

{
  "agent": {
    "model": "openai.gpt-5.6-luna",
    "instructions": "Use the workspace tools to complete the user's task."
  },
  "environment": {
    "type": "self_hosted",
    "workspace_directory": "/path/to/workspace",
    "capability_directories": ["/path/to/workspace/skills"]
  },
  "role_arn": "arn:aws:iam::123456789012:role/BedrockManagedAgentsPreviewInferenceServiceRole",
  "stream": false
}

Feld	Erforderlich	Beschreibung
agent	Ja	Agentenkonfiguration.
agent.model	Ja	Ein BMA-supported OpenAI-Modell, das in der ausgewählten Region und dem ausgewählten Konto verfügbar ist.
agent.instructions	Nein	Anweisungen für den Agenten.
agent.tools	Nein	Tooldefinitionen, wie z. B. die umgebungsbasierte STDIO-MCP-Konfiguration in Skills und Tools.
environment	Ja	Execution-environment Konfiguration.
role_arn	Ja für diesen Vorschau-Workflow	Die IAM-Rolle im anrufenden Konto, die BMA annimmt. Der Anrufer muss die Erlaubnis haben, es an BMA weiterzuleiten.
input	Nein für die beiden Beispiele für die Ausführungsumgebung	Optionale Ersteingabe, die als Zeichenfolge oder als Array von Eingabemeldungen bereitgestellt wird.
stream	Nein	Die Beispiele werden verwendetfalse, um eine JSON-Sitzungsressource zu empfangen. Der Standardwert ist false.

Unbekannte oder nicht unterstützte Konfigurationsfelder können zu einem Validierungsfehler führen. Verwenden Sie die dokumentierte Vorschauoberfläche, anstatt eine OpenAI-hosted Agenten-API-Anfrage zu kopieren, ohne sie für BMA anzupassen.

Konfiguration der Umgebung

Für eine selbst gehostete Umgebung:

{
  "type": "self_hosted",
  "workspace_directory": "/path/to/workspace",
  "capability_directories": ["/path/to/workspace/skills"]
}

Für eine AgentCore Runtime-Umgebung:

{
  "type": "aws_bedrock_agentcore",
  "runtime_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/example-runtime",
  "runtime_qualifier": "DEFAULT",
  "workspace_directory": "/mnt/workspace",
  "capability_directories": ["/mnt/workspace/skills"]
}

workspace_directoryist ein Pfad in der Ausführungsumgebung. capability_directoriesidentifiziert Verzeichnisse, die Fähigkeiten und andere auffindbare Fähigkeiten enthalten. Verwenden Sie absolute Pfade. Das Schema erlaubt maximal 32 eindeutige Capability-Verzeichniseinträge.

runtime_arnist erforderlich für. aws_bedrock_agentcore Verwenden Sie eine Runtime im vorgesehenen Konto und in der gewünschten Region und konfigurieren Sie die Sitzungsrolle so, dass diese Runtime aufgerufen und beendet wird. runtime_qualifierwählt den Runtime-Endpunkt aus; das Beispiel verwendetDEFAULT.

Antwort

Eine JSON-Sitzungsressource umfasst:

Feld	Description
id	Sitzungs-ID.
object	agent.session.
agent	Agenten-ID, Modell, Anweisungen und Tool-Konfiguration wurden behoben.
environment	Gelöste Umgebung, einschließlich ihrer ID.
role_arn	Rolle, die für vom Kunden autorisierte Sitzungsvorgänge verwendet wird.
status	idle, in_progress, oder failed.
created_at	Zeitstempel der Erstellung in Unix-Sekunden.
last_active_at	Zeitstempel der letzten Aktivität in Unix-Sekunden.
error	Fehlerdetails, falls vorhanden.

Eine neu erstellte, selbst gehostete Sitzung kann erfolgen, idle bevor ein Exec-Server angeschlossen wird. Hängen Sie die Umgebung an, bevor Sie sie zur Ausführung von Befehlen auffordern.

Sitzungen auflisten und abrufen

Sitzungen auflisten:

python3 bma_client.py GET '/openai/v1/agents/sessions?limit=20&order=desc'

Der Listenvorgang akzeptiert limitorder,after, undagent_id. orderist asc oderdesc. Geben Sie die vorherigen Seiten so weiterafter, last_id als ob has_more es wahr ist.

Rufen Sie eine Sitzung ab:

python3 bma_client.py GET "/openai/v1/agents/sessions/${SESSION_ID}"

Ereignisse einreichen

Nachrichten und Stornierungsanfragen werden über denselben Endpunkt eingereicht. Der Hauptteil der Anfrage muss ein nicht leeres events Array enthalten.

Nachrichtenereignis:

{
  "events": [{
    "type": "agent.session.input.message",
    "input": [{
      "role": "user",
      "content": [{"type": "input_text", "text": "Run the hello-docs skill."}]
    }]
  }]
}

Veranstaltung absagen:

{"events":[{"type":"agent.session.input.cancel"}]}

Die Vorschaubeispiele verwenden Texteingabe. Ein akzeptiertes Eingabeereignis bedeutet nicht, dass der resultierende Zug beendet ist.

Ereignisse streamen

An GET den /events Pfad der Sitzung senden und akzeptierentext/event-stream. Analysieren Sie SSE-Frames, anstatt zu versuchen, die gesamte Antwort als ein JSON-Objekt zu deserialisieren.

Ereignisse melden Änderungen des Sitzungsstatus und des Bearbeitungsfortschritts, einschließlich generiertem Text, Befehlsausgabe, Abschluss, Fehlschlag und Abbruch. Sorgen Sie dafür, dass Ihr Event-Parser Ereignistypen toleriert, die er nicht verwendet, und validieren Sie gleichzeitig die Felder, die er verwendet. Verwenden Sie langlebige Elemente für den Abgleich nach einem Verbindungsabbruch.

Ein ausführbares Beispiel finden Sie unter Stream-Fortschritt.

Elemente auflisten

python3 bma_client.py GET "/openai/v1/agents/sessions/${SESSION_ID}/items?limit=100&order=asc"

Abfrageparameter	Description
limit	Anzahl der Artikel, von 1 bis 100. Standard: 20.
order	asc oder desc. Standard: desc.
after	Undurchsichtiger Cursor von der vorherigen Seite. last_id

Die Antwort auf die Liste enthält datahas_more,first_id, undlast_id. Ein Nachrichtenelement enthält seine Rolle und seinen Inhalt. Ein Element zur Befehlsausführung kann den Befehl, das Arbeitsverzeichnis, die Ausgabe, den Exit-Code und die Dauer enthalten. Ein MCP-call Element umfasst die Serverbezeichnung, den Namen des Tools, die Argumente, das Ergebnis und den Status.

Löscht eine Sitzung

python3 bma_client.py DELETE "/openai/v1/agents/sessions/${SESSION_ID}"

Die Löschbestätigung identifiziert die gelöschte Sitzung. Nach dem Löschen steht die Sitzung nicht mehr zur weiteren Bearbeitung zur Verfügung. Bereinigen Sie separat bereitgestellte Ressourcen, wie unter Bereinigung beschrieben.

Fehler und Wiederholungsversuche

HTTP-Status	Was muss überprüft werden
400	Erforderliche Felder, unterstützte Feldnamen, Anforderungstypen, Modellkonfiguration und der Rollen-ARN.
401 oder 403	AWS Anmeldeinformationen, Region und Signaturdienst, BMA-Berechtigungen und Rollenvertrauensstellung. iam:PassRole
404	Endpunkt und Route, Ressourcen-ID, Vorschauzugriff oder eine API, die nicht bereitgestellt wurde.
409	Ein widersprüchlicher Sitzungs- oder Umgebungsvorgang. Re-read aktueller Status vor dem erneuten Versuch.
429	Anfrage oder Kontolimits. Reduzieren Sie die Parallelität und verwenden Sie Backoff mit Jitter.
500 oder 503	Dienst- oder Abhängigkeitsfehler. Behalten Sie die Anforderungs-ID bei und versuchen Sie es erneut, wenn dies sicher ist.

Erfassen Sie bei der Fehlerbehebung die Details des Antwortfehlers und die Anfrage-ID. Versuchen Sie erneut, Lesevorgänge mit begrenztem exponentiellem Backoff durchzuführen. Bevor Sie nach einer Netzwerkunterbrechung erneut versuchen, eine Erstellung oder Eingabe zu senden, überprüfen Sie, ob sie akzeptiert wurde, um doppelte Sitzungen oder Wiederholungen zu vermeiden.