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,407 @@
1
+ """The built-in router: a model picks the skill and extracts its arguments.
2
+
3
+ Each routed message takes two structured model calls, both charged to the run
4
+ through ``RoutingContext.generate``:
5
+
6
+ 1. **Select:** choose one of the eligible skills, or ask a question.
7
+ 2. **Extract:** fill in that skill's arguments, or ask a question.
8
+
9
+ Skill descriptions go only in trusted ``system`` instructions; the caller's
10
+ text is sent as untrusted ``user`` messages and the agent's earlier questions
11
+ as ``assistant`` messages. The router never guesses: anything ambiguous,
12
+ missing or invalid becomes a ``Clarification``.
13
+ """
14
+
15
+ import asyncio
16
+ import copy
17
+ from collections.abc import Iterable, Sequence
18
+ from typing import Any, Literal
19
+
20
+ from a2a.helpers import get_message_text
21
+ from a2a.types import Message, Role
22
+ from pydantic import (
23
+ BaseModel,
24
+ PydanticUserError,
25
+ ValidationError,
26
+ create_model,
27
+ )
28
+
29
+ from agentframe.authoring.definitions import SkillDefinition
30
+ from agentframe.errors import DefinitionError, InputValidationError, ProviderError
31
+ from agentframe.hosting.routing import Clarification, RoutingContext, SkillCall
32
+ from agentframe.models.base import Message as ModelMessage
33
+ from agentframe.models.base import Model, ModelSettings
34
+ from agentframe.runtime.generation import input_token_limit, output_schema
35
+ from agentframe.runtime.limits import RunLimits
36
+
37
+ NO_TEXT_QUESTION = "Please describe in text what you would like me to do."
38
+ """Asked when the caller's latest message has no text to route."""
39
+
40
+ UNCLEAR_REQUEST_QUESTION = "Could you tell me more about what you need?"
41
+ """Asked when the model neither chose a skill nor asked its own question."""
42
+
43
+ NULL_SCHEMA: dict[str, Any] = {"type": "null"}
44
+
45
+ SELECTION_INSTRUCTIONS = """\
46
+ You route a request to one of an agent's skills. The skills are:
47
+
48
+ {skills}
49
+
50
+ Read the conversation and choose the one skill that clearly matches the
51
+ caller's request: set "skill" to its id and "question" to null.
52
+ If the request is ambiguous, matches no skill, or is not a request at all,
53
+ set "skill" to null and "question" to one short question for the caller.
54
+ Never guess."""
55
+
56
+ EXTRACTION_INSTRUCTIONS = """\
57
+ The caller's request is for this skill:
58
+
59
+ {skill}
60
+
61
+ Fill in the skill's arguments using only values the caller stated in the
62
+ conversation. Never invent, assume or guess a value. Set an optional argument
63
+ to null unless the caller gave its value.
64
+ If a required value is missing or unclear, set "arguments" to null and
65
+ "question" to one short question asking for it. Otherwise set "question"
66
+ to null."""
67
+
68
+
69
+ class Selection(BaseModel):
70
+ """The selection call's reply: a skill ID, or a question for the caller.
71
+
72
+ ``selection_output`` narrows ``skill`` to the eligible IDs per request.
73
+ """
74
+
75
+ skill: str | None
76
+ question: str | None
77
+
78
+
79
+ class Extraction(BaseModel):
80
+ """The extraction call's reply: the skill's arguments, or a question.
81
+
82
+ ``extraction_output`` shows the model the skill's argument schema.
83
+ """
84
+
85
+ arguments: dict[str, Any] | None
86
+ question: str | None
87
+
88
+
89
+ class ModelRouter:
90
+ """Routes free-text A2A messages with a model, or asks the caller.
91
+
92
+ Opt-in: pass it as ``AgentApp(router=...)``. It uses only the model given
93
+ here, never the agent's, and the application owns and closes that model.
94
+ ``AgentApp`` checks the model and the skills' schemas before serving.
95
+ It can only choose among the skills the caller may run, and the runtime
96
+ still validates the arguments and checks permissions and policy before
97
+ the skill runs.
98
+
99
+ Args:
100
+ model: The router's model. It must support structured output. Pass
101
+ the agent's model explicitly to share it.
102
+ instructions: Extra trusted instructions for both routing calls,
103
+ such as domain hints. Never put untrusted content here.
104
+ model_settings: Settings for the routing calls. Each field set
105
+ overrides the library's and agent's value.
106
+ """
107
+
108
+ def __init__(
109
+ self,
110
+ model: Model,
111
+ *,
112
+ instructions: str | None = None,
113
+ model_settings: ModelSettings | None = None,
114
+ ) -> None:
115
+ self.model = model
116
+ self.instructions = instructions
117
+ self.model_settings = model_settings
118
+
119
+ async def route(
120
+ self,
121
+ conversation: Sequence[Message],
122
+ skills: Sequence[SkillDefinition],
123
+ ctx: RoutingContext,
124
+ ) -> SkillCall | Clarification:
125
+ """Select a skill and extract its arguments, or ask a question.
126
+
127
+ Args:
128
+ conversation: The task's A2A messages so far, oldest first. Only
129
+ their text parts are used.
130
+ skills: The skills this caller may run.
131
+ ctx: The run's routing context; both model calls are charged to it.
132
+
133
+ Returns:
134
+ The selected skill with only the arguments the model supplied, or
135
+ a question when the request is ambiguous, off-topic or incomplete,
136
+ or the extracted arguments are invalid.
137
+
138
+ Raises:
139
+ InputValidationError: No skill is available to this caller. No
140
+ model call is made.
141
+ UnsupportedCapabilityError: The router's model cannot produce the
142
+ selection or a skill's argument schema.
143
+ AgentFrameError: Other errors from ``ctx.generate``, such as a
144
+ limit, refusal or provider error.
145
+ """
146
+ if not skills:
147
+ raise InputValidationError("No skill is available to this caller")
148
+ if not get_message_text(conversation[-1]).strip():
149
+ return Clarification(NO_TEXT_QUESTION)
150
+ messages = model_messages(conversation)
151
+
152
+ selection = await self._select(messages, skills, ctx)
153
+ if isinstance(selection, Clarification):
154
+ return selection
155
+ return await self._extract(messages, selection, ctx)
156
+
157
+ async def _select(
158
+ self,
159
+ messages: list[ModelMessage],
160
+ skills: Sequence[SkillDefinition],
161
+ ctx: RoutingContext,
162
+ ) -> SkillDefinition | Clarification:
163
+ """Ask the model which skill the conversation is for."""
164
+ described = "\n\n".join(describe_skill(skill) for skill in skills)
165
+ reply = await ctx.generate(
166
+ self.model,
167
+ messages,
168
+ instructions=self._with_extra_instructions(
169
+ SELECTION_INSTRUCTIONS.format(skills=described)
170
+ ),
171
+ output=selection_output(skills),
172
+ model_settings=self.model_settings,
173
+ )
174
+ if reply.question or reply.skill is None:
175
+ return ask(reply.question)
176
+ return next(skill for skill in skills if skill.id == reply.skill)
177
+
178
+ async def _extract(
179
+ self,
180
+ messages: list[ModelMessage],
181
+ skill: SkillDefinition,
182
+ ctx: RoutingContext,
183
+ ) -> SkillCall | Clarification:
184
+ """Ask the model for the chosen skill's arguments, then validate them."""
185
+ reply = await ctx.generate(
186
+ self.model,
187
+ messages,
188
+ instructions=self._with_extra_instructions(
189
+ EXTRACTION_INSTRUCTIONS.format(skill=describe_skill(skill))
190
+ ),
191
+ output=extraction_output(skill),
192
+ model_settings=self.model_settings,
193
+ )
194
+ if reply.question or reply.arguments is None:
195
+ return ask(reply.question)
196
+ return checked_call(skill, reply.arguments)
197
+
198
+ def validate_skills(self, skills: Iterable[SkillDefinition]) -> None:
199
+ """Build the selection and extraction schemas for ``skills`` once.
200
+
201
+ ``AgentApp`` calls this when it is constructed, so a skill whose
202
+ arguments have no JSON schema fails before anything is served.
203
+ Whether the model's adapter accepts each schema is only known at the
204
+ first routing call (``UnsupportedCapabilityError``).
205
+
206
+ Args:
207
+ skills: Every skill of the hosted agent.
208
+
209
+ Raises:
210
+ DefinitionError: A skill's arguments cannot be described as a
211
+ JSON schema.
212
+ """
213
+ skills = list(skills)
214
+ output_schema(selection_output(skills))
215
+ for skill in skills:
216
+ try:
217
+ output_schema(extraction_output(skill))
218
+ except PydanticUserError:
219
+ raise DefinitionError(
220
+ f"ModelRouter cannot describe the arguments of skill "
221
+ f"'{skill.id}' as a JSON schema"
222
+ ) from None
223
+
224
+ async def validate_model(self, limits: RunLimits) -> None:
225
+ """Check that the router's model can route under ``limits``.
226
+
227
+ ``AgentApp`` calls this at server startup. Reading the model's
228
+ capabilities may do I/O, so it is bounded by ``limits.timeout_seconds``.
229
+
230
+ Args:
231
+ limits: The limits routing runs under (the agent's).
232
+
233
+ Raises:
234
+ DefinitionError: The model does not support structured output, or
235
+ reports no context window while ``max_input_tokens`` is unset.
236
+ ProviderError: The capabilities could not be read, or reading them
237
+ took longer than the timeout.
238
+ """
239
+ try:
240
+ async with asyncio.timeout(limits.timeout_seconds):
241
+ capabilities = await self.model.capabilities()
242
+ except TimeoutError:
243
+ raise ProviderError(
244
+ "Reading the router model's capabilities timed out", transient=True
245
+ ) from None
246
+ if not capabilities.structured_output:
247
+ raise DefinitionError(
248
+ "ModelRouter's model does not support structured output, which "
249
+ "routing needs"
250
+ )
251
+ try:
252
+ input_token_limit(limits, capabilities)
253
+ except DefinitionError as error:
254
+ raise DefinitionError(f"ModelRouter: {error.message}") from None
255
+
256
+ def _with_extra_instructions(self, instructions: str) -> str:
257
+ if self.instructions:
258
+ return f"{instructions}\n\n{self.instructions}"
259
+ return instructions
260
+
261
+
262
+ def ask(question: str | None) -> Clarification:
263
+ """Ask the model's question, or a generic one when it gave none."""
264
+ if question and question.strip():
265
+ return Clarification(question.strip())
266
+ return Clarification(UNCLEAR_REQUEST_QUESTION)
267
+
268
+
269
+ def model_messages(conversation: Sequence[Message]) -> list[ModelMessage]:
270
+ """Return the conversation's text as model messages, oldest first.
271
+
272
+ The caller's messages become ``user`` messages and the agent's earlier
273
+ questions ``assistant`` messages. Messages without text are left out.
274
+ """
275
+ messages = []
276
+ for message in conversation:
277
+ text = get_message_text(message)
278
+ if not text.strip():
279
+ continue
280
+ if message.role == Role.ROLE_AGENT:
281
+ messages.append(ModelMessage(role="assistant", content=text))
282
+ else:
283
+ messages.append(ModelMessage(role="user", content=text))
284
+ return messages
285
+
286
+
287
+ def describe_skill(skill: SkillDefinition) -> str:
288
+ """Describe a skill for the router's trusted instructions."""
289
+ lines = [f"id: {skill.id}", f"name: {skill.name}"]
290
+ if skill.tags:
291
+ lines.append(f"tags: {', '.join(skill.tags)}")
292
+ lines.append(f"description: {skill.description}")
293
+ return "\n".join(lines)
294
+
295
+
296
+ def selection_output(skills: Sequence[SkillDefinition]) -> type[Selection]:
297
+ """Return the ``Selection`` model: one of ``skills`` by ID, or a question.
298
+
299
+ Built per request, so the model can only name an eligible skill.
300
+ """
301
+ skill_ids = tuple(skill.id for skill in skills)
302
+ return create_model(
303
+ "Selection",
304
+ __base__=Selection,
305
+ skill=(Literal[skill_ids] | None, ...), # type: ignore[arg-type]
306
+ question=(str | None, ...),
307
+ )
308
+
309
+
310
+ def extraction_output(skill: SkillDefinition) -> type[Extraction]:
311
+ """Return the ``Extraction`` model for ``skill``: its arguments, or a question.
312
+
313
+ The model sees the skill's argument schema with every optional argument
314
+ nullable and required, so it says ``null`` rather than inventing a
315
+ value. The reply's ``arguments`` is only checked to be an object here:
316
+ ``checked_call`` validates it against the skill, so invalid values
317
+ become a question instead of a failed run.
318
+ """
319
+ arguments = nullable_optionals(skill.arguments_adapter.json_schema())
320
+ # References inside the arguments schema point at the root's $defs.
321
+ definitions = arguments.pop("$defs", None)
322
+ schema: dict[str, Any] = {
323
+ "title": "Extraction",
324
+ "type": "object",
325
+ "properties": {
326
+ "arguments": {"anyOf": [arguments, NULL_SCHEMA]},
327
+ "question": {"anyOf": [{"type": "string"}, NULL_SCHEMA]},
328
+ },
329
+ "required": ["arguments", "question"],
330
+ "additionalProperties": False,
331
+ }
332
+ if definitions:
333
+ schema["$defs"] = definitions
334
+
335
+ class SkillExtraction(Extraction):
336
+ # The schema sent to the model is the skill's, while validation of
337
+ # the reply stays loose (see ``Extraction``).
338
+ @classmethod
339
+ def model_json_schema(cls, *args: Any, **kwargs: Any) -> dict[str, Any]:
340
+ return copy.deepcopy(schema)
341
+
342
+ return SkillExtraction
343
+
344
+
345
+ def nullable_optionals(arguments_schema: dict[str, Any]) -> dict[str, Any]:
346
+ """Make every optional argument required and nullable, without its default.
347
+
348
+ The input is not modified. Without the default, the model has no value
349
+ to copy; ``null`` means the caller did not give one.
350
+ """
351
+ schema = copy.deepcopy(arguments_schema)
352
+ required = set(schema.get("required", ()))
353
+ properties = schema.get("properties", {})
354
+ for name, property_schema in properties.items():
355
+ if name in required:
356
+ continue
357
+ property_schema.pop("default", None)
358
+ properties[name] = {"anyOf": [property_schema, NULL_SCHEMA]}
359
+ schema["required"] = list(properties)
360
+ return schema
361
+
362
+
363
+ def checked_call(
364
+ skill: SkillDefinition, arguments: dict[str, Any]
365
+ ) -> SkillCall | Clarification:
366
+ """Validate extracted ``arguments`` against ``skill``.
367
+
368
+ Nulls for optional arguments are dropped first, so the skill's defaults
369
+ apply. Only the values the model supplied are returned.
370
+
371
+ Returns:
372
+ The skill call, or a question naming the invalid arguments (never
373
+ their values).
374
+ """
375
+ optional = optional_arguments(skill)
376
+ supplied = {
377
+ name: value
378
+ for name, value in arguments.items()
379
+ if not (value is None and name in optional)
380
+ }
381
+ try:
382
+ validated = skill.arguments_adapter.validate_python(supplied)
383
+ except ValidationError as error:
384
+ return Clarification(invalid_arguments_question(skill, error))
385
+ return SkillCall(skill.id, validated.model_dump(mode="json", exclude_unset=True))
386
+
387
+
388
+ def optional_arguments(skill: SkillDefinition) -> set[str]:
389
+ """Return the names of the skill's arguments that have defaults."""
390
+ schema = skill.arguments_adapter.json_schema()
391
+ return set(schema.get("properties", {})) - set(schema.get("required", ()))
392
+
393
+
394
+ def invalid_arguments_question(skill: SkillDefinition, error: ValidationError) -> str:
395
+ """Ask for valid values of the arguments ``error`` names, without values.
396
+
397
+ Only the skill's own argument names are shown, never names the model
398
+ made up.
399
+ """
400
+ names: list[str] = []
401
+ for item in error.errors(include_input=False, include_url=False):
402
+ name = item["loc"][0] if item["loc"] else None
403
+ if name in skill.argument_names and name not in names:
404
+ names.append(name)
405
+ if not names:
406
+ return UNCLEAR_REQUEST_QUESTION
407
+ return f"Could you give valid values for: {', '.join(names)}?"
@@ -0,0 +1,52 @@
1
+ """Bound the size of a request body before anything else reads it.
2
+
3
+ The app reads every ``/a2a`` body here first, counting bytes as they arrive,
4
+ so an oversized body is never held in full or parsed. A declared
5
+ ``Content-Length`` above the limit is refused without reading anything;
6
+ chunked bodies, which declare no length, are refused as soon as the count
7
+ passes the limit.
8
+ """
9
+
10
+ from starlette.requests import Request
11
+ from starlette.types import Message
12
+
13
+
14
+ async def read_body_within(request: Request, max_bytes: int) -> bytes | None:
15
+ """Read ``request``'s body, or stop once it is larger than ``max_bytes``.
16
+
17
+ Args:
18
+ request: The incoming request, whose body has not been read yet.
19
+ max_bytes: The largest body accepted.
20
+
21
+ Returns:
22
+ The whole body, or ``None`` when it is larger than ``max_bytes``.
23
+ """
24
+ declared = request.headers.get("content-length", "")
25
+ if declared.isdigit() and int(declared) > max_bytes:
26
+ return None
27
+ body = bytearray()
28
+ async for chunk in request.stream():
29
+ body += chunk
30
+ if len(body) > max_bytes:
31
+ return None
32
+ return bytes(body)
33
+
34
+
35
+ def with_body(request: Request, body: bytes) -> Request:
36
+ """Return a copy of ``request`` that replays an already read ``body``.
37
+
38
+ A request's stream can be read only once. The copy shares the request's
39
+ scope, including ``request.state``, so later readers such as the A2A SDK
40
+ see the same request and body. After the body, it passes on the
41
+ connection's own messages, such as a client disconnect.
42
+ """
43
+ body_sent = False
44
+
45
+ async def receive() -> Message:
46
+ nonlocal body_sent
47
+ if body_sent:
48
+ return await request.receive()
49
+ body_sent = True
50
+ return {"type": "http.request", "body": body, "more_body": False}
51
+
52
+ return Request(request.scope, receive)