agentframe-py 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentframe/__init__.py +170 -0
- agentframe/authoring/__init__.py +1 -0
- agentframe/authoring/agent.py +75 -0
- agentframe/authoring/context.py +123 -0
- agentframe/authoring/decorators.py +202 -0
- agentframe/authoring/definitions.py +372 -0
- agentframe/authoring/services.py +176 -0
- agentframe/cli.py +293 -0
- agentframe/errors.py +194 -0
- agentframe/hosting/__init__.py +1 -0
- agentframe/hosting/a2a_executor.py +569 -0
- agentframe/hosting/admission.py +69 -0
- agentframe/hosting/app.py +617 -0
- agentframe/hosting/card.py +138 -0
- agentframe/hosting/dedup.py +193 -0
- agentframe/hosting/draining_server.py +47 -0
- agentframe/hosting/host.py +143 -0
- agentframe/hosting/lifecycle.py +81 -0
- agentframe/hosting/model_router.py +407 -0
- agentframe/hosting/request_size.py +52 -0
- agentframe/hosting/routing.py +349 -0
- agentframe/models/__init__.py +1 -0
- agentframe/models/base.py +264 -0
- agentframe/models/foundry.py +570 -0
- agentframe/models/ollama.py +320 -0
- agentframe/models/strict_schema.py +211 -0
- agentframe/py.typed +0 -0
- agentframe/runtime/__init__.py +1 -0
- agentframe/runtime/generation.py +725 -0
- agentframe/runtime/limits.py +124 -0
- agentframe/runtime/options.py +50 -0
- agentframe/runtime/runtime.py +449 -0
- agentframe/runtime/tools.py +216 -0
- agentframe/runtime/usage.py +40 -0
- agentframe/security/__init__.py +1 -0
- agentframe/security/authentication.py +265 -0
- agentframe/security/authorization.py +66 -0
- agentframe/security/entra.py +260 -0
- agentframe/security/execution_policy.py +241 -0
- agentframe/security/principal.py +16 -0
- agentframe/testing.py +135 -0
- agentframe_py-0.1.0.dist-info/METADATA +570 -0
- agentframe_py-0.1.0.dist-info/RECORD +46 -0
- agentframe_py-0.1.0.dist-info/WHEEL +4 -0
- agentframe_py-0.1.0.dist-info/entry_points.txt +2 -0
- agentframe_py-0.1.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,569 @@
|
|
|
1
|
+
"""Run A2A requests through the AgentFrame ``Runtime``.
|
|
2
|
+
|
|
3
|
+
The official A2A SDK owns the protocol: JSON-RPC parsing, the task store and
|
|
4
|
+
task lifecycle. This module is the bridge it calls for each message: read which
|
|
5
|
+
skill to run, run it through the ``Runtime`` and publish the outcome on the task.
|
|
6
|
+
|
|
7
|
+
Outcomes map to native A2A results as follows:
|
|
8
|
+
|
|
9
|
+
- Callers name a skill through the AgentFrame skill-call extension: they
|
|
10
|
+
activate it with the ``A2A-Extensions`` HTTP header, put the skill id in
|
|
11
|
+
message metadata under ``agentframe.skill`` and the arguments in exactly one
|
|
12
|
+
JSON data part. A malformed skill call is a JSON-RPC ``InvalidParams`` error
|
|
13
|
+
and creates no task (the app's request handler checks it before the SDK
|
|
14
|
+
creates one).
|
|
15
|
+
- A message without the extension is free text. The application's
|
|
16
|
+
``SkillRouter`` selects the skill and its arguments from the task's
|
|
17
|
+
conversation, or asks the caller a question; without a router free text is
|
|
18
|
+
refused before a task exists. Routing time counts against the run's timeout,
|
|
19
|
+
and the router's model calls (through ``RoutingContext.generate``) are
|
|
20
|
+
charged to the same run as the selected skill.
|
|
21
|
+
- A result becomes the artifact of a ``COMPLETED`` task: a ``str`` is one text
|
|
22
|
+
part, anything else one data part ``{"value": ...}`` in Pydantic JSON mode.
|
|
23
|
+
- Unknown skills, invalid arguments and denied permissions end the task in
|
|
24
|
+
``REJECTED``; every other failure ends it in ``FAILED``; ``CancelTask`` ends
|
|
25
|
+
it in ``CANCELED`` through AgentFrame's ``CancelledError``.
|
|
26
|
+
- A result or question larger than the host's ``max_response_bytes`` ends the
|
|
27
|
+
task in ``FAILED`` with ``LimitExceededError``; none of it is sent.
|
|
28
|
+
- A router's question leaves the task in ``INPUT_REQUIRED``; the caller answers
|
|
29
|
+
with a new message in the same task, which is routed again with the earlier
|
|
30
|
+
messages.
|
|
31
|
+
- Router exceptions and timeouts end the task in ``FAILED``; invalid router
|
|
32
|
+
decisions in ``REJECTED``. ``AgentFrameError``s raised while routing, such
|
|
33
|
+
as limit, refusal and provider errors, keep their safe messages; any other
|
|
34
|
+
router exception gets a generic one.
|
|
35
|
+
|
|
36
|
+
Every task status carries the run's ``invocation_id`` and a ``usage``
|
|
37
|
+
snapshot in its metadata: ``input_tokens``, ``output_tokens``,
|
|
38
|
+
``total_tokens`` (``null`` when unknown), ``estimated``, ``model_calls``
|
|
39
|
+
and ``tool_calls``.
|
|
40
|
+
A cancelled task reports the usage its run had reached when it was cancelled.
|
|
41
|
+
|
|
42
|
+
Every run that ends ``FAILED`` is logged as a warning with its invocation ID
|
|
43
|
+
and safe message; skill and router exceptions are logged with their traceback.
|
|
44
|
+
Arguments, prompts and results are never logged.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
import asyncio
|
|
48
|
+
import logging
|
|
49
|
+
import uuid
|
|
50
|
+
from dataclasses import dataclass
|
|
51
|
+
from typing import Any
|
|
52
|
+
|
|
53
|
+
from a2a.helpers import get_data_parts, new_data_part, new_task, new_text_part
|
|
54
|
+
from a2a.server.agent_execution import AgentExecutor, RequestContext
|
|
55
|
+
from a2a.server.context import ServerCallContext
|
|
56
|
+
from a2a.server.events import EventQueue
|
|
57
|
+
from a2a.server.tasks import TaskUpdater
|
|
58
|
+
from a2a.types import Message, Part, Task, TaskState
|
|
59
|
+
from a2a.utils.errors import InvalidParamsError
|
|
60
|
+
from pydantic_core import to_json, to_jsonable_python
|
|
61
|
+
|
|
62
|
+
from agentframe.authoring.agent import Agent
|
|
63
|
+
from agentframe.errors import (
|
|
64
|
+
AgentFrameError,
|
|
65
|
+
CancelledError,
|
|
66
|
+
DefinitionError,
|
|
67
|
+
InputValidationError,
|
|
68
|
+
LimitExceededError,
|
|
69
|
+
OutputValidationError,
|
|
70
|
+
PermissionDeniedError,
|
|
71
|
+
)
|
|
72
|
+
from agentframe.hosting.admission import RUN_SLOT_STATE_KEY, RunSlot
|
|
73
|
+
from agentframe.hosting.card import SKILL_CALL_EXTENSION_URI
|
|
74
|
+
from agentframe.hosting.routing import (
|
|
75
|
+
Clarification,
|
|
76
|
+
SkillCall,
|
|
77
|
+
SkillRouter,
|
|
78
|
+
eligible_skills,
|
|
79
|
+
new_routing_context,
|
|
80
|
+
route,
|
|
81
|
+
)
|
|
82
|
+
from agentframe.runtime.generation import RunAccounting
|
|
83
|
+
from agentframe.runtime.limits import RunLimits
|
|
84
|
+
from agentframe.runtime.options import RunOptions
|
|
85
|
+
from agentframe.runtime.runtime import Runtime
|
|
86
|
+
from agentframe.security.principal import Principal
|
|
87
|
+
|
|
88
|
+
SKILL_METADATA_NAMESPACE = "agentframe."
|
|
89
|
+
"""Prefix of the message metadata keys the skill-call extension owns."""
|
|
90
|
+
|
|
91
|
+
SKILL_METADATA_KEY = "agentframe.skill"
|
|
92
|
+
"""Message metadata key that names the skill to run."""
|
|
93
|
+
|
|
94
|
+
PRINCIPAL_STATE_KEY = "agentframe.principal"
|
|
95
|
+
"""``ServerCallContext.state`` key holding the authenticated caller."""
|
|
96
|
+
|
|
97
|
+
SKILL_FAILED_MESSAGE = "The skill failed."
|
|
98
|
+
"""What callers see when a skill raises an exception that is not AgentFrame's."""
|
|
99
|
+
|
|
100
|
+
CANCELLED_MESSAGE = "The task was cancelled."
|
|
101
|
+
"""What callers see on a task cancelled with ``CancelTask``."""
|
|
102
|
+
|
|
103
|
+
HOST_MISCONFIGURED_MESSAGE = "The agent is not configured correctly."
|
|
104
|
+
"""What callers see for a ``DefinitionError``, whose message names internals."""
|
|
105
|
+
|
|
106
|
+
RESPONSE_TOO_LARGE_MESSAGE = "The result exceeds the host's response size limit"
|
|
107
|
+
"""What callers see when a result or question is over ``max_response_bytes``."""
|
|
108
|
+
|
|
109
|
+
logger = logging.getLogger(__name__)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def is_skill_call(requested_extensions: set[str]) -> bool:
|
|
113
|
+
"""Return whether a request activated the skill-call extension.
|
|
114
|
+
|
|
115
|
+
Only such a request is a skill call; any other message is free text.
|
|
116
|
+
|
|
117
|
+
Args:
|
|
118
|
+
requested_extensions: Extension URIs the caller activated with the
|
|
119
|
+
``A2A-Extensions`` header.
|
|
120
|
+
"""
|
|
121
|
+
return SKILL_CALL_EXTENSION_URI in requested_extensions
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def read_skill_call(message: Message) -> SkillCall:
|
|
125
|
+
"""Read the skill id and JSON arguments of a skill-call extension message.
|
|
126
|
+
|
|
127
|
+
Call it only for requests that activated the extension. The skill id comes
|
|
128
|
+
from the ``agentframe.skill`` metadata key and the arguments from the
|
|
129
|
+
message's only part, a data part holding a JSON object. Other metadata
|
|
130
|
+
keys starting with ``agentframe.`` are unknown fields; keys outside that
|
|
131
|
+
namespace belong to other extensions and are ignored.
|
|
132
|
+
|
|
133
|
+
Args:
|
|
134
|
+
message: The caller's message.
|
|
135
|
+
|
|
136
|
+
Returns:
|
|
137
|
+
The requested skill call; the runtime validates the skill id and
|
|
138
|
+
arguments.
|
|
139
|
+
|
|
140
|
+
Raises:
|
|
141
|
+
InvalidParamsError: The message names no skill, carries unknown
|
|
142
|
+
``agentframe.`` metadata, or does not have exactly one part that is
|
|
143
|
+
a JSON object data part. This is a protocol error, not a task
|
|
144
|
+
failure, and the message is never reinterpreted as free text.
|
|
145
|
+
"""
|
|
146
|
+
metadata = dict(message.metadata.items())
|
|
147
|
+
unknown = sorted(
|
|
148
|
+
key
|
|
149
|
+
for key in metadata
|
|
150
|
+
if key.startswith(SKILL_METADATA_NAMESPACE) and key != SKILL_METADATA_KEY
|
|
151
|
+
)
|
|
152
|
+
if unknown:
|
|
153
|
+
raise InvalidParamsError(
|
|
154
|
+
f"Unknown skill-call metadata fields: {', '.join(unknown)}."
|
|
155
|
+
)
|
|
156
|
+
skill_id = metadata.get(SKILL_METADATA_KEY)
|
|
157
|
+
if not isinstance(skill_id, str) or not skill_id:
|
|
158
|
+
raise InvalidParamsError(
|
|
159
|
+
f"A skill call must name a skill in metadata '{SKILL_METADATA_KEY}'."
|
|
160
|
+
)
|
|
161
|
+
data = get_data_parts(message.parts)
|
|
162
|
+
if len(message.parts) != 1 or len(data) != 1 or not isinstance(data[0], dict):
|
|
163
|
+
raise InvalidParamsError(
|
|
164
|
+
"A skill call must have exactly one part: a data part holding a "
|
|
165
|
+
"JSON object of arguments."
|
|
166
|
+
)
|
|
167
|
+
return SkillCall(skill_id, data[0])
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
@dataclass(frozen=True)
|
|
171
|
+
class _RunningTask:
|
|
172
|
+
"""What a cancel needs to know about a task whose run is going."""
|
|
173
|
+
|
|
174
|
+
accounting: RunAccounting
|
|
175
|
+
call_context: ServerCallContext
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
class RuntimeExecutor(AgentExecutor):
|
|
179
|
+
"""Executes each A2A message as one ``Runtime.run`` of the agent's skill.
|
|
180
|
+
|
|
181
|
+
Args:
|
|
182
|
+
agent: The hosted agent instance.
|
|
183
|
+
runtime: The runtime that validates, authorizes and limits every run.
|
|
184
|
+
router: Selects the skill for free-text messages. ``None`` means the
|
|
185
|
+
request handler refuses free text before it reaches the executor.
|
|
186
|
+
limits_ceiling: The host's ceiling, which caps the limits of every
|
|
187
|
+
run and of routing. ``None`` caps nothing.
|
|
188
|
+
max_response_bytes: The largest result or question a task may
|
|
189
|
+
return, measured as by ``check_response_size``. ``None`` bounds
|
|
190
|
+
nothing.
|
|
191
|
+
"""
|
|
192
|
+
|
|
193
|
+
def __init__(
|
|
194
|
+
self,
|
|
195
|
+
agent: Agent,
|
|
196
|
+
runtime: Runtime,
|
|
197
|
+
router: SkillRouter | None = None,
|
|
198
|
+
limits_ceiling: RunLimits | None = None,
|
|
199
|
+
max_response_bytes: int | None = None,
|
|
200
|
+
) -> None:
|
|
201
|
+
self._agent = agent
|
|
202
|
+
self._runtime = runtime
|
|
203
|
+
self._router = router
|
|
204
|
+
self._limits_ceiling = limits_ceiling
|
|
205
|
+
self._max_response_bytes = max_response_bytes
|
|
206
|
+
# Each running task, so a cancel can report its usage and a shutdown
|
|
207
|
+
# can cancel it on behalf of the caller who started it.
|
|
208
|
+
self._running: dict[str, _RunningTask] = {}
|
|
209
|
+
|
|
210
|
+
def running_tasks(self) -> dict[str, ServerCallContext]:
|
|
211
|
+
"""Return the ID and starting call context of every task now running.
|
|
212
|
+
|
|
213
|
+
Tasks waiting for input have no run, so they are not included.
|
|
214
|
+
"""
|
|
215
|
+
return {
|
|
216
|
+
task_id: running.call_context for task_id, running in self._running.items()
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
|
|
220
|
+
"""Run the requested or routed skill and publish the task's new state.
|
|
221
|
+
|
|
222
|
+
A run the app admitted holds its ``RunSlot`` until it ends: completed,
|
|
223
|
+
failed, cancelled, timed out or asking the caller a question.
|
|
224
|
+
"""
|
|
225
|
+
slot: RunSlot | None = context.call_context.state.get(RUN_SLOT_STATE_KEY)
|
|
226
|
+
if slot is not None:
|
|
227
|
+
slot.start()
|
|
228
|
+
try:
|
|
229
|
+
await self._run_task(context, event_queue)
|
|
230
|
+
finally:
|
|
231
|
+
if slot is not None:
|
|
232
|
+
slot.release()
|
|
233
|
+
|
|
234
|
+
async def _run_task(self, context: RequestContext, event_queue: EventQueue) -> None:
|
|
235
|
+
"""Start or resume the task, run it and record its accounting."""
|
|
236
|
+
# The SDK always fills these in before calling the executor.
|
|
237
|
+
task_id, context_id, message = (
|
|
238
|
+
context.task_id,
|
|
239
|
+
context.context_id,
|
|
240
|
+
context.message,
|
|
241
|
+
)
|
|
242
|
+
assert task_id is not None and context_id is not None
|
|
243
|
+
assert message is not None
|
|
244
|
+
if context.current_task is None:
|
|
245
|
+
await event_queue.enqueue_event(
|
|
246
|
+
new_task(
|
|
247
|
+
task_id,
|
|
248
|
+
context_id,
|
|
249
|
+
TaskState.TASK_STATE_SUBMITTED,
|
|
250
|
+
history=[message],
|
|
251
|
+
)
|
|
252
|
+
)
|
|
253
|
+
task = TaskUpdater(event_queue, task_id, context_id)
|
|
254
|
+
invocation_id = _new_invocation_id()
|
|
255
|
+
accounting = RunAccounting()
|
|
256
|
+
# Stored on the task now so a later cancel can report the same ID.
|
|
257
|
+
await task.update_status(
|
|
258
|
+
TaskState.TASK_STATE_WORKING,
|
|
259
|
+
metadata=run_metadata(invocation_id, accounting),
|
|
260
|
+
)
|
|
261
|
+
self._running[task_id] = _RunningTask(accounting, context.call_context)
|
|
262
|
+
try:
|
|
263
|
+
await self._execute(context, task, invocation_id, accounting)
|
|
264
|
+
finally:
|
|
265
|
+
self._running.pop(task_id, None)
|
|
266
|
+
|
|
267
|
+
async def _execute(
|
|
268
|
+
self,
|
|
269
|
+
context: RequestContext,
|
|
270
|
+
task: TaskUpdater,
|
|
271
|
+
invocation_id: str,
|
|
272
|
+
accounting: RunAccounting,
|
|
273
|
+
) -> None:
|
|
274
|
+
"""Run the skill and publish its result, question or failure."""
|
|
275
|
+
principal: Principal | None = context.call_context.state.get(
|
|
276
|
+
PRINCIPAL_STATE_KEY
|
|
277
|
+
)
|
|
278
|
+
started_at = asyncio.get_running_loop().time()
|
|
279
|
+
# noinspection PyBroadException
|
|
280
|
+
try:
|
|
281
|
+
call = await self._choose_skill(
|
|
282
|
+
context, principal, started_at, invocation_id, accounting
|
|
283
|
+
)
|
|
284
|
+
if isinstance(call, Clarification):
|
|
285
|
+
check_response_size(
|
|
286
|
+
call.question.encode(), self._max_response_bytes, invocation_id
|
|
287
|
+
)
|
|
288
|
+
await publish_input_required(
|
|
289
|
+
task, call.question, invocation_id, accounting
|
|
290
|
+
)
|
|
291
|
+
return
|
|
292
|
+
# The executor shares the runtime's pipeline under its own invocation ID.
|
|
293
|
+
# noinspection PyProtectedMember
|
|
294
|
+
result = await self._runtime._run_invocation(
|
|
295
|
+
invocation_id,
|
|
296
|
+
self._agent,
|
|
297
|
+
call.skill,
|
|
298
|
+
call.arguments,
|
|
299
|
+
principal,
|
|
300
|
+
# Hosted callers cannot send per-run options in M3.
|
|
301
|
+
RunOptions(),
|
|
302
|
+
started_at,
|
|
303
|
+
accounting,
|
|
304
|
+
self._limits_ceiling,
|
|
305
|
+
)
|
|
306
|
+
part = result_part(result.value, invocation_id, self._max_response_bytes)
|
|
307
|
+
except AgentFrameError as error:
|
|
308
|
+
error.invocation_id = invocation_id
|
|
309
|
+
_log_failed_run(error)
|
|
310
|
+
await publish_failure(task, error, accounting)
|
|
311
|
+
return
|
|
312
|
+
except Exception:
|
|
313
|
+
# Skill exceptions may carry submitted values or secrets, so the
|
|
314
|
+
# caller gets a generic message and only the log keeps the details,
|
|
315
|
+
# under the run's ID that the caller can quote.
|
|
316
|
+
failure = AgentFrameError(SKILL_FAILED_MESSAGE, invocation_id=invocation_id)
|
|
317
|
+
logger.exception("Skill failed (invocation_id=%s)", invocation_id)
|
|
318
|
+
await publish_failure(task, failure, accounting)
|
|
319
|
+
return
|
|
320
|
+
await publish_result(task, part, invocation_id, accounting)
|
|
321
|
+
|
|
322
|
+
async def _choose_skill(
|
|
323
|
+
self,
|
|
324
|
+
context: RequestContext,
|
|
325
|
+
principal: Principal | None,
|
|
326
|
+
started_at: float,
|
|
327
|
+
invocation_id: str,
|
|
328
|
+
accounting: RunAccounting,
|
|
329
|
+
) -> SkillCall | Clarification:
|
|
330
|
+
"""Read the skill call, or ask the router about the free-text message."""
|
|
331
|
+
message = context.message
|
|
332
|
+
assert message is not None
|
|
333
|
+
if is_skill_call(context.requested_extensions):
|
|
334
|
+
# The request handler has already refused malformed skill calls.
|
|
335
|
+
return read_skill_call(message)
|
|
336
|
+
# The request handler refuses free text when there is no router.
|
|
337
|
+
assert self._router is not None
|
|
338
|
+
conversation = [*_earlier_messages(context.current_task), message]
|
|
339
|
+
definition = type(self._agent).definition()
|
|
340
|
+
ctx = new_routing_context(
|
|
341
|
+
self._agent,
|
|
342
|
+
invocation_id,
|
|
343
|
+
principal,
|
|
344
|
+
started_at,
|
|
345
|
+
accounting,
|
|
346
|
+
self._limits_ceiling,
|
|
347
|
+
# Routing requests pass the same model-request checks as the skill's.
|
|
348
|
+
# noinspection PyProtectedMember
|
|
349
|
+
self._runtime._policy,
|
|
350
|
+
)
|
|
351
|
+
return await route(
|
|
352
|
+
self._router, conversation, eligible_skills(definition, principal), ctx
|
|
353
|
+
)
|
|
354
|
+
|
|
355
|
+
async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
|
|
356
|
+
"""Mark the task ``CANCELED``; the SDK then stops the running skill.
|
|
357
|
+
|
|
358
|
+
The SDK calls this only for the caller's own unfinished task, then
|
|
359
|
+
cancels the ``execute`` call. That ``asyncio`` cancellation unwinds
|
|
360
|
+
the run, so per-run services are still cleaned up. The task reports
|
|
361
|
+
the ``invocation_id`` its run started with and the usage it reached.
|
|
362
|
+
"""
|
|
363
|
+
task_id, context_id = context.task_id, context.context_id
|
|
364
|
+
assert task_id is not None and context_id is not None
|
|
365
|
+
task = TaskUpdater(event_queue, task_id, context_id)
|
|
366
|
+
invocation_id: str | None = None
|
|
367
|
+
current_task = context.current_task
|
|
368
|
+
if current_task is not None:
|
|
369
|
+
stored = dict(current_task.metadata.items()).get("invocation_id")
|
|
370
|
+
invocation_id = stored if isinstance(stored, str) else None
|
|
371
|
+
# A task waiting for input has no running run, so it used nothing more.
|
|
372
|
+
running = self._running.get(task_id)
|
|
373
|
+
accounting = running.accounting if running else RunAccounting()
|
|
374
|
+
await publish_failure(
|
|
375
|
+
task,
|
|
376
|
+
CancelledError(CANCELLED_MESSAGE, invocation_id=invocation_id),
|
|
377
|
+
accounting,
|
|
378
|
+
)
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def result_part(value: Any, invocation_id: str, max_bytes: int | None = None) -> Part:
|
|
382
|
+
"""Serialize a skill's validated result as one A2A part.
|
|
383
|
+
|
|
384
|
+
Args:
|
|
385
|
+
value: The skill's validated return value.
|
|
386
|
+
invocation_id: The run that produced it, for the error.
|
|
387
|
+
max_bytes: The host's ``max_response_bytes``, checked against the
|
|
388
|
+
UTF-8 text or the compact JSON of ``{"value": ...}``. ``None``
|
|
389
|
+
bounds nothing.
|
|
390
|
+
|
|
391
|
+
Returns:
|
|
392
|
+
One text part for a ``str``; otherwise one data part ``{"value": ...}``
|
|
393
|
+
holding the value in Pydantic JSON mode.
|
|
394
|
+
|
|
395
|
+
Raises:
|
|
396
|
+
OutputValidationError: The value cannot be represented as JSON.
|
|
397
|
+
LimitExceededError: The serialized value is larger than ``max_bytes``.
|
|
398
|
+
"""
|
|
399
|
+
if isinstance(value, str):
|
|
400
|
+
check_response_size(value.encode(), max_bytes, invocation_id)
|
|
401
|
+
return new_text_part(value)
|
|
402
|
+
try:
|
|
403
|
+
data = {"value": to_jsonable_python(value)}
|
|
404
|
+
except (TypeError, ValueError):
|
|
405
|
+
raise OutputValidationError(
|
|
406
|
+
"The skill returned a value that cannot be serialized as JSON",
|
|
407
|
+
invocation_id=invocation_id,
|
|
408
|
+
) from None
|
|
409
|
+
check_response_size(to_json(data), max_bytes, invocation_id)
|
|
410
|
+
return new_data_part(data)
|
|
411
|
+
|
|
412
|
+
|
|
413
|
+
def check_response_size(
|
|
414
|
+
content: bytes, max_bytes: int | None, invocation_id: str
|
|
415
|
+
) -> None:
|
|
416
|
+
"""Fail when content to send the caller is larger than ``max_bytes``.
|
|
417
|
+
|
|
418
|
+
Only the content is measured, not the JSON-RPC envelope around it.
|
|
419
|
+
|
|
420
|
+
Args:
|
|
421
|
+
content: A result's UTF-8 text or compact JSON, or a question's text.
|
|
422
|
+
max_bytes: The host's ``max_response_bytes``; ``None`` bounds nothing.
|
|
423
|
+
invocation_id: The run that produced the content, for the error.
|
|
424
|
+
|
|
425
|
+
Raises:
|
|
426
|
+
LimitExceededError: The content is larger than ``max_bytes``. The
|
|
427
|
+
task fails instead; none of the content is sent or logged.
|
|
428
|
+
"""
|
|
429
|
+
if max_bytes is not None and len(content) > max_bytes:
|
|
430
|
+
raise LimitExceededError(
|
|
431
|
+
RESPONSE_TOO_LARGE_MESSAGE, invocation_id=invocation_id
|
|
432
|
+
)
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
def failure_state(error: AgentFrameError) -> TaskState:
|
|
436
|
+
"""Return the A2A task state that reports ``error``.
|
|
437
|
+
|
|
438
|
+
Args:
|
|
439
|
+
error: Why the run did not complete.
|
|
440
|
+
|
|
441
|
+
Returns:
|
|
442
|
+
``REJECTED`` when the request itself was refused (unknown skill,
|
|
443
|
+
invalid arguments, permission or policy denied), ``CANCELED`` for a
|
|
444
|
+
cancelled run, and ``FAILED`` for everything else.
|
|
445
|
+
"""
|
|
446
|
+
if isinstance(error, CancelledError):
|
|
447
|
+
return TaskState.TASK_STATE_CANCELED
|
|
448
|
+
if isinstance(error, InputValidationError | PermissionDeniedError):
|
|
449
|
+
return TaskState.TASK_STATE_REJECTED
|
|
450
|
+
return TaskState.TASK_STATE_FAILED
|
|
451
|
+
|
|
452
|
+
|
|
453
|
+
async def publish_result(
|
|
454
|
+
task: TaskUpdater, part: Part, invocation_id: str, accounting: RunAccounting
|
|
455
|
+
) -> None:
|
|
456
|
+
"""Publish a run's result as the task's artifact and complete the task."""
|
|
457
|
+
await task.add_artifact([part], name="result")
|
|
458
|
+
await task.update_status(
|
|
459
|
+
TaskState.TASK_STATE_COMPLETED,
|
|
460
|
+
metadata=run_metadata(invocation_id, accounting),
|
|
461
|
+
)
|
|
462
|
+
|
|
463
|
+
|
|
464
|
+
async def publish_failure(
|
|
465
|
+
task: TaskUpdater, error: AgentFrameError, accounting: RunAccounting
|
|
466
|
+
) -> None:
|
|
467
|
+
"""End the task in the state for ``error`` with its safe message.
|
|
468
|
+
|
|
469
|
+
A ``DefinitionError`` names agent internals, so it is logged and callers
|
|
470
|
+
get a generic message instead. An error without an invocation ID (one
|
|
471
|
+
raised before any run started) is given a new one, so every task reports
|
|
472
|
+
an ID.
|
|
473
|
+
"""
|
|
474
|
+
message = task.new_agent_message([new_text_part(_safe_message(error))])
|
|
475
|
+
await task.update_status(
|
|
476
|
+
failure_state(error),
|
|
477
|
+
message=message,
|
|
478
|
+
metadata=run_metadata(error.invocation_id or _new_invocation_id(), accounting),
|
|
479
|
+
)
|
|
480
|
+
|
|
481
|
+
|
|
482
|
+
async def publish_input_required(
|
|
483
|
+
task: TaskUpdater, question: str, invocation_id: str, accounting: RunAccounting
|
|
484
|
+
) -> None:
|
|
485
|
+
"""Ask the caller a question, leaving the task in ``INPUT_REQUIRED``.
|
|
486
|
+
|
|
487
|
+
Args:
|
|
488
|
+
task: The task to update.
|
|
489
|
+
question: Safe text telling the caller what is missing or ambiguous.
|
|
490
|
+
invocation_id: The run that needs the answer.
|
|
491
|
+
accounting: The run's usage so far.
|
|
492
|
+
"""
|
|
493
|
+
message = task.new_agent_message([new_text_part(question)])
|
|
494
|
+
await task.update_status(
|
|
495
|
+
TaskState.TASK_STATE_INPUT_REQUIRED,
|
|
496
|
+
message=message,
|
|
497
|
+
metadata=run_metadata(invocation_id, accounting),
|
|
498
|
+
)
|
|
499
|
+
|
|
500
|
+
|
|
501
|
+
def run_metadata(invocation_id: str, accounting: RunAccounting) -> dict[str, Any]:
|
|
502
|
+
"""Return the task metadata that identifies a run and reports its usage.
|
|
503
|
+
|
|
504
|
+
Only safe values are included: the run's ID, token counts (``None`` when
|
|
505
|
+
unknown, including while a model call is still running, as when a task is
|
|
506
|
+
cancelled), whether any count is estimated, and the numbers of model
|
|
507
|
+
and tool calls.
|
|
508
|
+
"""
|
|
509
|
+
usage = accounting.current_usage()
|
|
510
|
+
return {
|
|
511
|
+
"invocation_id": invocation_id,
|
|
512
|
+
"usage": {
|
|
513
|
+
"input_tokens": usage.input_tokens,
|
|
514
|
+
"output_tokens": usage.output_tokens,
|
|
515
|
+
"total_tokens": usage.total_tokens,
|
|
516
|
+
"estimated": usage.estimated,
|
|
517
|
+
"model_calls": accounting.model_calls,
|
|
518
|
+
"tool_calls": accounting.tool_calls,
|
|
519
|
+
},
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
def _earlier_messages(task: Task | None) -> list[Message]:
|
|
524
|
+
"""Return a task's messages before the current one, oldest first.
|
|
525
|
+
|
|
526
|
+
The SDK keeps the agent's latest question in the task status, not yet in
|
|
527
|
+
the history, and appends the caller's new message only after the run.
|
|
528
|
+
"""
|
|
529
|
+
if task is None:
|
|
530
|
+
return []
|
|
531
|
+
earlier = list(task.history)
|
|
532
|
+
if task.status.HasField("message"):
|
|
533
|
+
earlier.append(task.status.message)
|
|
534
|
+
return earlier
|
|
535
|
+
|
|
536
|
+
|
|
537
|
+
def _log_failed_run(error: AgentFrameError) -> None:
|
|
538
|
+
"""Log a run that ends ``FAILED``, so operators can find it by its ID.
|
|
539
|
+
|
|
540
|
+
Only the error's class and safe message are logged: never its cause,
|
|
541
|
+
which may hold arguments, prompts or provider payloads. Rejections are
|
|
542
|
+
the caller's doing and are not logged; definition errors are logged by
|
|
543
|
+
``_safe_message``.
|
|
544
|
+
"""
|
|
545
|
+
if isinstance(error, DefinitionError) or failure_state(error) != (
|
|
546
|
+
TaskState.TASK_STATE_FAILED
|
|
547
|
+
):
|
|
548
|
+
return
|
|
549
|
+
logger.warning(
|
|
550
|
+
"Run failed (invocation_id=%s): %s: %s",
|
|
551
|
+
error.invocation_id,
|
|
552
|
+
type(error).__name__,
|
|
553
|
+
error.message,
|
|
554
|
+
)
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
def _safe_message(error: AgentFrameError) -> str:
|
|
558
|
+
if isinstance(error, DefinitionError):
|
|
559
|
+
logger.error(
|
|
560
|
+
"Agent definition error (invocation_id=%s): %s",
|
|
561
|
+
error.invocation_id,
|
|
562
|
+
error.message,
|
|
563
|
+
)
|
|
564
|
+
return HOST_MISCONFIGURED_MESSAGE
|
|
565
|
+
return error.message
|
|
566
|
+
|
|
567
|
+
|
|
568
|
+
def _new_invocation_id() -> str:
|
|
569
|
+
return str(uuid.uuid4())
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""Admit at most a fixed number of hosted runs at once.
|
|
2
|
+
|
|
3
|
+
The app takes a ``RunSlot`` for each ``SendMessage`` before the A2A SDK sees
|
|
4
|
+
it and refuses the request when none is free; nothing ever waits for a slot.
|
|
5
|
+
The executor marks the slot as started when the run begins and releases it
|
|
6
|
+
when the run ends, however it ends. When the SDK refuses a message before
|
|
7
|
+
running it, the run never starts and the app releases the slot instead.
|
|
8
|
+
|
|
9
|
+
Everything runs on one event loop, so a plain counter needs no lock.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
RUN_SLOT_STATE_KEY = "agentframe.run_slot"
|
|
13
|
+
"""``ServerCallContext.state`` key holding the request's ``RunSlot``."""
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class RunAdmission:
|
|
17
|
+
"""Counts running runs and refuses any beyond ``max_runs``.
|
|
18
|
+
|
|
19
|
+
Args:
|
|
20
|
+
max_runs: How many runs may be admitted at once.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def __init__(self, max_runs: int) -> None:
|
|
24
|
+
self._max_runs = max_runs
|
|
25
|
+
self._running = 0
|
|
26
|
+
|
|
27
|
+
def try_admit(self) -> "RunSlot | None":
|
|
28
|
+
"""Take a slot for one run, or return ``None`` when all are in use."""
|
|
29
|
+
if self._running >= self._max_runs:
|
|
30
|
+
return None
|
|
31
|
+
self._running += 1
|
|
32
|
+
return RunSlot(self)
|
|
33
|
+
|
|
34
|
+
@property
|
|
35
|
+
def running(self) -> int:
|
|
36
|
+
"""How many admitted runs have not yet released their slot."""
|
|
37
|
+
return self._running
|
|
38
|
+
|
|
39
|
+
def _release(self) -> None:
|
|
40
|
+
self._running -= 1
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class RunSlot:
|
|
44
|
+
"""One admitted run's place; releasing it more than once has no effect."""
|
|
45
|
+
|
|
46
|
+
def __init__(self, admission: RunAdmission) -> None:
|
|
47
|
+
self._admission = admission
|
|
48
|
+
self.started = False
|
|
49
|
+
self._released = False
|
|
50
|
+
|
|
51
|
+
def start(self) -> None:
|
|
52
|
+
"""Hand the slot to the run, which now releases it when it ends.
|
|
53
|
+
|
|
54
|
+
The executor calls this before it publishes the task, and the SDK
|
|
55
|
+
responds to ``SendMessage``, even with ``returnImmediately``, only
|
|
56
|
+
after that first task event. So the app sees ``started`` before it
|
|
57
|
+
decides whether to release the slot itself. Should a run ever start
|
|
58
|
+
after the app released its slot, the run goes ahead but its own
|
|
59
|
+
release is a no-op, so the count never goes negative.
|
|
60
|
+
"""
|
|
61
|
+
self.started = True
|
|
62
|
+
|
|
63
|
+
def release(self) -> None:
|
|
64
|
+
"""Free the slot for another run."""
|
|
65
|
+
if self._released:
|
|
66
|
+
return
|
|
67
|
+
self._released = True
|
|
68
|
+
# noinspection PyProtectedMember
|
|
69
|
+
self._admission._release()
|