Files
devplacepy/devplacepy/services/devii/agents/actions.py
T
retoor 3bfde87fdb Introduce Devii agents subsystem with supervisor, policy, and evals
- Add agents package: controller, runner, store, tools, actions, evals, policy
- Wire agents into Devii service, session, registry, CLI, and dispatcher
- Extend database schema and config for agent persistence
- Add news and telegram bridge updates plus landing UI and docs
- Cover agents, news, and telegram flows with unit tests
2026-10-26 02:54:44 +01:00

149 lines
5.4 KiB
Python

# retoor <retoor@molodetz.nl>
from __future__ import annotations
from ..actions.spec import Action, Param
def field(
name: str, description: str, required: bool = False, kind: str = "string"
) -> Param:
return Param(
name=name,
location="body",
description=description,
required=required,
type=kind,
)
AGENT_ACTIONS: tuple[Action, ...] = (
Action(
name="agent_start",
method="LOCAL",
path="",
summary="Clone yourself into a supervised async subagent for slow or multi-step work",
description=(
"Spawns a subagent with its own context window, its own category system prompt, "
"and your effective tool list plus the category extras. Returns a process uid "
"immediately; the subagent runs in the background while you keep chatting. Poll "
"with agent_status, read the outcome with agent_result, stop it with agent_cancel. "
"The four-part contract is mandatory: a clear objective in task, the exact shape "
"of the answer in output_format, tool and source guidance via tools_extra, and "
"hard task boundaries inside task. Only the orchestrator talks to the user: a "
"subagent that needs input pauses as needs_user and you resume it through "
"agent_result with an answer."
),
handler="agent",
requires_auth=True,
params=(
field(
"category",
"One of research, files, planning-report, email-triage, containers, "
"long-mutation. Picks the subagent system prompt, tool extras, and budgets.",
required=True,
),
field(
"task",
"Complete self-contained objective plus hard boundaries: what to do, what "
"to touch, and what to leave alone. The subagent has no other context.",
required=True,
),
field(
"output_format",
"Exact shape of the expected answer, e.g. 'a markdown table with columns "
"name, url, verdict, one row per finding' or 'the list of paths changed "
"plus one summary line'.",
required=True,
),
field(
"tools_extra",
"Optional extra tool names beyond the inherited set, e.g. a tool the "
"category does not include by default.",
kind="array",
),
field(
"budget_hint",
"Effort scale: quick (half budgets), standard, or deep (double budgets). "
"Match it to the query complexity; default standard.",
),
field("label", "Optional short human-readable label for the run."),
),
),
Action(
name="agent_status",
method="LOCAL",
path="",
summary="Check one subagent run's progress without blocking",
handler="agent",
requires_auth=False,
params=(field("uid", "Process uid returned by agent_start.", required=True),),
),
Action(
name="agent_result",
method="LOCAL",
path="",
summary="Read a subagent run's outcome, or resume it with an answer",
description=(
"Returns the final result once the run is done, or the current progress "
"otherwise. When the run pauses as needs_user, pass answer to resume it: "
"ask the user first through ui_prompt, then hand their answer back here."
),
handler="agent",
requires_auth=False,
params=(
field("uid", "Process uid returned by agent_start.", required=True),
field(
"answer",
"Answer to the pending needs_user question. Only used while the run "
"is paused as needs_user; ignored otherwise.",
),
),
),
Action(
name="agent_cancel",
method="LOCAL",
path="",
summary="Stop a running or paused subagent run",
handler="agent",
requires_auth=True,
params=(field("uid", "Process uid returned by agent_start.", required=True),),
),
Action(
name="agent_list",
method="LOCAL",
path="",
summary="List your subagent runs and their statuses",
handler="agent",
requires_auth=False,
params=(
field(
"status",
"Filter by status: queued, running, needs_user, done, failed, "
"cancelled, interrupted.",
),
),
),
Action(
name="ask_user",
method="LOCAL",
path="",
summary="Pause this subagent run and ask the user one question (subagents only)",
description=(
"Pauses the run as needs_user. The orchestrator asks the user through "
"its own channel and resumes the run with the answer, which arrives as "
"this call's result. Call it alone, then stop: end the turn with a short "
"note of what is awaited and call no further tools until the answer arrives."
),
handler="agent",
requires_auth=False,
params=(
field(
"question",
"The exact question for the user, including the decision or target.",
required=True,
),
),
),
)