forked from retoor/devplacepy
- 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
149 lines
5.4 KiB
Python
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,
|
|
),
|
|
),
|
|
),
|
|
)
|