23 Agent Deployment
Wenn Sie einen Agent bereitstellen, wird Ihr Agent zu einer gehosteten Anwendung.
Sie können einen Agent in demselben AI-Compute bereitstellen, das an seinen Playground angeschlossen ist, oder in einem anderen AI-Compute. Wenn Sie die neuesten Änderungen an Ihrem Agent in dem angehängten AI-Compute bereitstellen, stellt der bereitgestellte Agent einen Snapshot des Agent zum Zeitpunkt des Deployments dar. Um den bereitgestellten Agent auf die neueste Version zu aktualisieren, müssen Sie den Agent erneut bereitstellen.
Jeder Agent verfügt über eine stabile Deployment-URL, die vom eindeutigen Agent-Schlüssel abhängt. Wenn Sie den Agent mehrmals erneut bereitstellen, wird der Agent hinter der Deployment-URL überschrieben.
- Ein Agent kann jeweils nur in einem AI-Compute-Cluster bereitgestellt werden.
- Wenn Sie denselben Agent mehrmals in demselben AI-Compute-Cluster bereitstellen, wird die zuvor bereitgestellte Iteration des Agent überschrieben.
Nachdem Sie einen Agent bereitgestellt haben, können Sie die Chat-URI abrufen, um programmgesteuert Abfragen abzufragen und Antworten vom Agent über die Registerkarte Details Ihres Agent abzurufen.
Die Endpunkt-URL ist stabil und an jeden Agent gebunden. Die URL enthält die eindeutige Agent-ID, die jedem Agent zugewiesen ist. Mit anderen Worten: Wenn Sie das Deployment eines Agent rückgängig machen und ihn erneut bereitstellen, bleibt die URL unverändert. Der Vorteil ist, dass Sie den Clientcode, der den Endpunkt aufruft, nicht ändern müssen. Der Nachteil besteht darin, dass Sie einen Agent in der Produktion überschreiben können.
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}oci-regionentspricht der AI Data Platform-Instanzregion;agentIdist die eindeutige ID, die dem Agent zugeordnet istprotocolist das Kommunikationsprotokoll:chat, das dem OpenAI Responses-API-Format folgt, unda2a, das dem Agent-zu-Agent-Kommunikationsprotokoll folgt. Beide Protokolle sind für jeden Agent-Endpunkt verfügbar. Weitere Informationen finden Sie unter A2A-Agent-Deployment.
Hinweis:
Auf der Registerkarte "Details" werden zwei AI-Berechnungen aufgeführt. Mit An AI Compute angehängt wird der Agent im Playground getestet. Das Deployment in AI Compute hostet den bereitgestellten Agent.Das Feld "Endpunkt-URL" wird aufgefüllt, nachdem Sie Ihren Agent bereitgestellt haben. Sie können diese Endpunkt-URL über Ihre Produktionsanwendung aufrufen.
Agent bereitstellen
Sie stellen Agents bereit, die Sie erstellt und konfiguriert haben, damit andere Benutzer sie in Ihrer AI Data Platform-Instanz anzeigen und verwenden können.
- Klicken Sie neben dem Agent auf
Aktionen und dann auf Bereitstellen. Sie können auch auf den Agent-Namen klicken und oben rechts auf Bereitstellen klicken.
Agent mit OAuth2 bereitstellen
Sie können Agents bereitstellen, die Sie erstellt und für die Verwendung der OAuth2-Authentifizierung konfiguriert haben, um eine Verbindung zu externen Identitätsprovidern herzustellen.
- Klicken Sie neben dem Agent auf Aktionen und dann auf Bereitstellen. Sie können auch auf den Agent-Namen klicken und oben rechts auf Bereitstellen klicken.
Deployment eines Agent aufheben
Sie können das Deployment von Agents aufheben, für die Sie MANAGE-Berechtigungen haben, sodass sie nicht mehr verwendet werden können.
- Klicken Sie neben dem Agent auf Aktionen, und klicken Sie auf Deployment aufheben.
A2A-Agent-Deployment
Das Agent2Agent-Protokoll (A2A) ist ein offener Standard für die Kommunikation zwischen unabhängigen KI-Agents, einschließlich Agents, die mit verschiedenen Frameworks erstellt, von verschiedenen Anbietern gehostet oder als undurchsichtige Remote-Systeme ausgeführt werden.
Der Zweck besteht darin, diesen Agents ein gemeinsames Interaktionsmodell zu geben, damit sie die Fähigkeiten des jeweils anderen erkennen, unterstützte Eingabe-/Ausgabeformate aushandeln, Aufgaben delegieren oder gemeinsam bearbeiten und Informationen sicher austauschen können, ohne internen Speicher, Tools oder Implementierungsdetails verfügbar zu machen. Weitere Informationen finden Sie unter Agent2Agent (A2A)-Protokoll.
A2A soll die Agent-Interoperabilität lösen: Anstatt dass jede Agent-Integration benutzerdefiniert ist, kann ein Client oder ein anderer Agent mit jedem A2A-konformen Remote-Agent mit einem allgemeinen Satz von Konzepten und Vorgängen interagieren. Die Spezifikation konzentriert sich auf Nachrichten, Aufgaben, Teile, Artefakte, Streaming-Updates und Push-Benachrichtigungen. Sie unterstützt synchrone Antworten, asynchrone Arbeit mit langer Ausführungszeit, Streaming und Authentifizierungs-/Sicherheitsmuster im Enterprise-Stil.
In Oracle AI Data Platform erhalten alle bereitgestellten Agents einen /A2A-Aufrufpfad, der von A2A-Clientanwendungen aufgerufen werden kann.
Was ist eine Agent Card?
Eine Agent Card ist ein JSON-Metadatendokument, das von einem A2A-Server veröffentlicht wird. In AIDP ist der A2A-Server der AI-Compute, der Ihr Agent-Deployment hostet.
Die Karte beschreibt die Identität des Agent, den Serviceendpunkt, unterstützte Protokolle/Transporte, Fähigkeiten, Fähigkeiten, unterstützte Eingabe-/Ausgabemodi und Authentifizierungsanforderungen. Clients ermitteln damit, ob der Agent geeignet ist und wie er aufgerufen werden kann. Eine ordnungsgemäß dokumentierte Agent-Karte ist eine Anforderung des A2A-Protokolls.
Agent-Karten in AI Data Platform Workbench haben entweder den Status "Entwurf", d.h. der Agent wurde nicht bereitgestellt, oder "Veröffentlicht", d.h. die Karte wurde neben dem Agent bereitgestellt.
Agent-Kartenaktionen
Während der Entwicklung eines Agent ist die Karte im Menü "Aktionen" des Agent verfügbar.
- Der Kartenentwurf spiegelt den aktuellen Status des Agenten in der Entwicklung wider.
- Die veröffentlichte Karte entspricht einem Snapshot der Karte, die beim Deployment des Agent erstellt wurde. Die veröffentlichte Karte gibt den Status des bereitgestellten Agent an.
Agent-Kartenfelder
AI Data Platform Workbench unterstützt eine Teilmenge der aktuellen A2A-Protokoll-Agent-Kartenfelder, die hier verfügbar sind: A2A-Protokoll - Agent-Karte.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
name |
Ja | Ein menschenlesbarer Name für den Agent. Beispiel: "Rezept-Agent" |
description |
Ja | Eine menschenlesbare Beschreibung des Agenten, die Benutzer und andere Agenten dabei unterstützt, seinen Zweck zu verstehen. Beispiel: "Agent, der Benutzern beim Kochen und Rezepten hilft." |
Agent Version |
Ja | Die Version des Agent. Beispiel: "1.0.0" |
Documentation URL |
Nr. | Eine URL mit zusätzlicher Dokumentation zum Agent. |
Provider - Organization |
Nr. | Der Serviceprovider des Agent. |
Provider - URL |
Nr. | Die URL des Serviceproviders. |
Capabilities |
Ja | A2A-Fähigkeitssatz, der vom Agent unterstützt wird.
Nur |
Skills
|
Ja | Skills stellen die Fähigkeiten eines Agents dar. Es ist weitgehend ein beschreibendes Konzept, stellt aber eine fokussiertere Gruppe von Verhaltensweisen dar, bei denen der Agent wahrscheinlich erfolgreich sein wird. Skills stellen ein Array von AgentSkill dar. |
Jede AgentSkill besteht aus mehreren Feldern, in denen die Fähigkeiten des Agent dokumentiert werden. Die Definition der Agent-Skills auf der Agent-Karte ist der zeitaufwendigste Vorgang und ein iterativer Prozess. Skills können (zusammen mit dem Rest der Agent-Karte) vor dem Deployment in der Entwurfs-Agent-Karte bearbeitet werden.
Hinweis:
inputModes, outputModes und securityRequirements werden von AI Data Platform Workbench bereitgestellt und können nicht geändert werden.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
Skill ID |
Ja | Eine eindeutige ID für den Skill des Agents. |
Skill Name |
Ja | Ein menschenlesbarer Name für den Skill. |
Description |
Ja | Eine detaillierte Beschreibung des Skills. |
Tags |
Ja | Eine Gruppe von Schlüsselwörtern, die die Fähigkeiten des Skills beschreiben. |
Examples |
Nr. | Beispiel-Prompts oder Szenarios, die dieser Skill verarbeiten kann. |
Agent-Deployment-Endpunkt A2A-Pfad
Ein /a2a-Pfad wird zusätzlich zu /chat in der URL eines bereitgestellten Agent angezeigt.
Beispiel: Ein Agent stellt diese Pfade externen Clients zur Verfügung:
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chathttps://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a
Beide Pfade (/chat, /a2a) können von separaten Clients belegt werden.
Sessionvariablen in A2A
Werte von Sessionvariablen können an einen A2A-Agent im Feld metadata der Nachricht übergeben werden. Im folgenden JSON-Snippet wird die Payload einer Benutzernachricht angezeigt, die an den a2a-Agent mit drei Sessionvariablen ausgegeben wurde: userName, geoLocation und os:
{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"contextId": "session_12345",
"taskId": "task_67890",
"message": {
"role": "user",
"parts": [
{
"text": "What is the current status of my order?",
}
],
"metadata": {
"sessionvariables.userName": "George",
"sessionvariables.geoLocation": “Dallas, TX”,
"sessionvariables.os": "mobile_ios"
}
}
},
"id": "rpc-99821"
}
Beispiel: A2A-Agent mit OCI-CLI aufrufen (Nicht-Streaming)
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"id": "<your-request-id>",
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"configuration": {
"acceptedOutputModes": [
"text/plain",
"text"
]
},
"message": {
"contextId": "<your-context-id>",
"kind": "message",
"messageId": "<your-message-id>",
"parts": [
{
"kind": "text",
"text": "What is the capital of India?"
}
],
"role": "user"
}
}
}' \
--request-headers '{
"x-session-id": "<your-session-id>",
"dh-user-principal": "<your-user-principal>"
}' \
--target-uri " <your-a2a-agent-endpoint-url>"
Beispiel: A2A-Agent mit OCI-CLI (Streaming) aufrufen
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"id": "<your-request-id>",
"jsonrpc": "2.0",
"method": "message/stream",
"params": {
"configuration": {
"acceptedOutputModes": [
"text/plain",
"text"
]
},
"message": {
"contextId": "<your-context-id>",
"kind": "message",
"messageId": " <your-message-id>",
"parts": [
{
"kind": "text",
"text": "What is the capital of India?"
}
],
"role": "user"
}
}
}' \
--request-headers '{
"x-session-id": "<your-session-id>",
"dh-user-principal": "<user-principal>"
}' \
--target-uri "<your-a2a-agent-endpoint-url>"
Beispiel: A2A Client SDK
import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
AgentCard,
Message,
Part,
Role,
TextPart,
SendMessageRequest,
MessageSendParams,
MessageSendConfiguration,
Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)
class OCIAuth(httpx.Auth):
"""httpx auth implementation using OCI signer via requests auth adapter."""
def __init__(self, signer: oci.signer.AbstractBaseSigner):
self._requests_auth = _OCIRequestsAuth(signer)
def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
req = RequestsRequest(
method=request.method,
url=str(request.url),
headers=dict(request.headers),
data=request.content,
)
prepared: RequestsPreparedRequest = req.prepare()
prepared = self._requests_auth(prepared)
request.headers.update(dict(prepared.headers))
yield request
def getOCIAuth():
conf = oci.config.from_file(profile_name="DEFAULT")
token_file = conf['security_token_file']
token = None
with open(token_file, 'r') as f:
token = f.read()
private_key = oci.signer.load_private_key_from_file(conf['key_file'])
signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
auth = OCIAuth(signer=signer)
return auth
async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
"""Call an agent using the A2A protocol."""
try:
# Initialize OCI signer
#headers = {"dh-user-principal": "dh-user"}
headers = {"Accept": "*/*",
"dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
agent_card = await _get_agent_card(agent_url,auth)
print(f"Agent card is {agent_card}")
client = A2AClient(httpx_client=hc, agent_card=agent_card)
# Create message
message = Message(
message_id=str(uuid.uuid4()),
context_id=context_id,
role=Role.user,
parts=[Part(root=TextPart(text=query))],
metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
)
request = SendMessageRequest(
id=str(uuid.uuid4()), # Add the required id field
params=MessageSendParams(
message=message,
configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
),
)
#json_string = json.dumps(message, indent=4)
print(f"Send request : {request}")
response = await client.send_message(request)
logging.info("Received response from A2A server: %s", response.root.result)
# Extract response
result = response.root.result
# Handle different response types
if isinstance(result, Task):
# Task response
if result.artifacts:
# Extract text from artifacts
texts = []
for artifact in result.artifacts:
for part in artifact.parts:
if hasattr(part, "root") and hasattr(part.root, "text"):
texts.append(part.root.text)
return "\n".join(texts) if texts else "Task completed with no text response"
elif result.status and result.status.message:
logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
if result.status.state== "failed":
print("Failure observed in Task invocation")
for m_part in result.status.message.parts:
print(f"Error message { m_part.root.text}")
return get_message_text(result.status.message)
else:
return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"
elif isinstance(result, Message):
return get_message_text(result)
else:
logging.warning(f"Unexpected response type: {type(result)}")
return "Received response but unable to extract text"
except Exception as ex:
logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
return f"Error communicating with agent: {str(ex)}"
async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
"""Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
try:
async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
agent_card = await _get_agent_card(agent_url)
if not agent_card:
return "No Agent Card Found"
print(f"Agent card is {agent_card}")
client = A2AClient(httpx_client=hc, agent_card=agent_card)
message = Message(
message_id=str(uuid.uuid4()),
context_id=context_id,
role=Role.user,
parts=[Part(root=TextPart(text=query))],
)
request = SendStreamingMessageRequest(
id=str(uuid.uuid4()),
params=MessageSendParams(
message=message,
configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
),
)
print("Invoking Remote Agent request (beautified JSON):")
print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
# Expected event types:
# - TaskStatusUpdateEvent (working/in-progress)
# - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
final_artifact_text_parts: list[str] = []
async for event in client.send_message_streaming(request):
# Print each SSE event as-is (SDK object)
print(f"[A2A stream event] {event}")
try:
result = getattr(event.root, "result", None)
if not result:
continue
# TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
# extract by attribute presence.
artifact = getattr(result, "artifact", None)
if artifact and getattr(artifact, "parts", None):
for part in artifact.parts:
root = getattr(part, "root", None)
txt = getattr(root, "text", None)
if txt:
final_artifact_text_parts.append(txt)
except Exception:
# Keep streaming even if an event can't be parsed
continue
return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
except Exception as ex:
logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
return f"Error communicating with agent: {str(ex)}"Agent-Entwurfskarte bearbeiten
Sie können die Agent-Karte für einen Agent bearbeiten, der noch nicht bereitgestellt ist.
- Klicken Sie auf Aktionen und dann auf Agent-Karte anzeigen und Agent-Karte entwerfen.
- Klicken Sie auf Edit.
- Sie können die Ansicht wechseln, indem Sie oben rechts auf Formular oder JSON klicken. Die JSON-Ansicht ist vollständiger, aber schreibgeschützt. Sie können Felder nur in der Formularansicht bearbeiten.
- Klicken Sie auf Skill hinzufügen, um Skills hinzuzufügen, die Sie für A2A-Clients verfügbar machen möchten.
Veröffentlichte Agent-Karte bearbeiten
Sie können eine veröffentlichte Agent-Karte ändern, ohne dass das Deployment eines Agents rückgängig gemacht oder erneut bereitgestellt wird.
Hinweis:
Änderungen, die Sie an einer veröffentlichten Karte vornehmen, werden sofort in der Datei agent-card.json wiedergegeben, auf die A2A-Clients zugreifen können.- Klicken Sie auf Aktionen, Agent-Karte anzeigen und Veröffentlichte Agent-Karte.
- Klicken Sie auf Edit.
- Klicken Sie auf Skill hinzufügen, um Skills hinzuzufügen, die Sie für A2A-Clients verfügbar machen möchten.
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json