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.
Files changed (46) hide show
  1. agentframe/__init__.py +170 -0
  2. agentframe/authoring/__init__.py +1 -0
  3. agentframe/authoring/agent.py +75 -0
  4. agentframe/authoring/context.py +123 -0
  5. agentframe/authoring/decorators.py +202 -0
  6. agentframe/authoring/definitions.py +372 -0
  7. agentframe/authoring/services.py +176 -0
  8. agentframe/cli.py +293 -0
  9. agentframe/errors.py +194 -0
  10. agentframe/hosting/__init__.py +1 -0
  11. agentframe/hosting/a2a_executor.py +569 -0
  12. agentframe/hosting/admission.py +69 -0
  13. agentframe/hosting/app.py +617 -0
  14. agentframe/hosting/card.py +138 -0
  15. agentframe/hosting/dedup.py +193 -0
  16. agentframe/hosting/draining_server.py +47 -0
  17. agentframe/hosting/host.py +143 -0
  18. agentframe/hosting/lifecycle.py +81 -0
  19. agentframe/hosting/model_router.py +407 -0
  20. agentframe/hosting/request_size.py +52 -0
  21. agentframe/hosting/routing.py +349 -0
  22. agentframe/models/__init__.py +1 -0
  23. agentframe/models/base.py +264 -0
  24. agentframe/models/foundry.py +570 -0
  25. agentframe/models/ollama.py +320 -0
  26. agentframe/models/strict_schema.py +211 -0
  27. agentframe/py.typed +0 -0
  28. agentframe/runtime/__init__.py +1 -0
  29. agentframe/runtime/generation.py +725 -0
  30. agentframe/runtime/limits.py +124 -0
  31. agentframe/runtime/options.py +50 -0
  32. agentframe/runtime/runtime.py +449 -0
  33. agentframe/runtime/tools.py +216 -0
  34. agentframe/runtime/usage.py +40 -0
  35. agentframe/security/__init__.py +1 -0
  36. agentframe/security/authentication.py +265 -0
  37. agentframe/security/authorization.py +66 -0
  38. agentframe/security/entra.py +260 -0
  39. agentframe/security/execution_policy.py +241 -0
  40. agentframe/security/principal.py +16 -0
  41. agentframe/testing.py +135 -0
  42. agentframe_py-0.1.0.dist-info/METADATA +570 -0
  43. agentframe_py-0.1.0.dist-info/RECORD +46 -0
  44. agentframe_py-0.1.0.dist-info/WHEEL +4 -0
  45. agentframe_py-0.1.0.dist-info/entry_points.txt +2 -0
  46. 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()