akka-agents

name: akka-agents description: Orchestrate Akka Java SDK Agent work across durable behavior profiles, governed behavior documents, prompt design, structured responses, tools, memory, streaming, workflow orchestration, guardrails, evaluation, and testing. Use when the task spans more than one agent concern.

Akka Agents

Use this broad skill to route multi-concern Akka Agent work. For a single implementation concern, load the focused skill directly.

Worker/tool/capability alignment

For generated AI-first SaaS app work, treat the agent runtime, autonomous task loop, or governed artifact in scope as a software-worker harness concern, not as the product operation or authorization boundary. Keep the chain explicit:

software worker
→ Akka Agent/AutonomousAgent harness or focused governance artifact
→ actor adapter (`agent_tool_call`, `human_chat_tool_plan`, workflow/timer/consumer/API/MCP/internal adapter as applicable)
→ governed tool
→ backend capability
→ Akka/frontend implementation

Human surface availability, prompt/skill/reference text, model output, task instructions, and Akka tool registration do not grant tool authority. A model-facing tool, loader, or autonomous task action may be exposed only when the active workstream tool catalog, governed tool contract, backend AuthContext, and ToolPermissionBoundary explicitly allow that actor adapter; denials and approval-required paths must fail closed and be traced.

Required reading

• ../docs/agent-component-selection-guide.md
• ../docs/agent-runtime-invocation-pattern.md
• ../docs/agent-workstream-application-architecture.md when the agent is user-facing in a workstream
• ../docs/governed-agent-substrate.md when managed/generative SaaS agent behavior is in scope
• ../references/generated-saas-runtime-completion.md

Routing

Generated SaaS requirements

For all generated-app model-backed agent behavior, normal runtime must use a concrete Akka Agent or AutonomousAgent path with:

• backend-selected AuthContext and authorization
• active governed AgentDefinition/behavior profile for every agent, including internal helpers, evaluators, replay/test-console agents, and autonomous workers
• governed prompt/skill/reference/model/tool-boundary resolution
• compact per-agent skill names/descriptions/hints appended to the assembled system prompt
• readSkill(skillId) registered for every managed agent and authorized/traced at call time
• registered tools via the Akka Agent effect APIs or equivalent autonomous-agent setup, resolved from governed logical tool/capability ids and/or approved backend-owned Java binding ids/classes
• provider/model configuration fail-closed behavior
• durable work/audit traces
• tests that prove allowed, denied, and failure paths

Do not replace this with direct provider calls, deterministic canned responses, prompt-only security, frontend-only decisions, or fixture/model-less normal runtime.

Workstream tool interpretation

For user-facing workstream agents, distinguish the governed workstream tool from the Akka tool mechanism. A governed workstream tool is the capability-backed operation with AuthContext, tenant/customer scope, schemas, idempotency, policy/approval, audit/work trace, and tests. Akka @FunctionTool, component tools, MCP tools, and loader tools are only model-facing exposure adapters for the subset of governed tools assigned to the AI-backed actor through the active workstream tool catalog and ToolPermissionBoundary.

Human-requested chat execution is a separate human-backed adapter: the selected workstream agent may interpret a natural-language request, propose a detailed tool plan, bind explicit human confirmation to that exact plan, and then execute each governed-tool invocation through backend authorization and per-tool transaction/idempotency rules. That path does not grant the AI-backed agent extra authority, and prompt, skill, or reference text cannot expand the catalog. Trace records must distinguish surface_action, human_chat_tool_plan, and agent_tool_call sources and preserve requestedBy, confirmedBy, denials, partial failures, and result surfaces.

Design checklist

Before implementation, decide:

• request-based Agent vs AutonomousAgent vs Workflow + Agent
• governed managed AgentDefinition identity for the agent, regardless of component type
• input/output contract and fallback/error shape
• prompt layers and governed document refs
• compact skill manifest entries and mandatory readSkill(skillId) loader behavior
• tool set, stored logical tool ids / Java binding ids or classes, and tool permission boundary
• memory/session behavior
• AuthContext, tenant/customer/data scope, approval gates, and side-effect authority
• trace facts and redaction rules
• endpoint/workflow/consumer caller and validation path

Validation

Use akka-agent-testing plus component/endpoint/workflow tests appropriate to the caller. At minimum cover successful model response, provider/config missing fail-closed behavior, authorization denial, tool denial, malformed/unsafe output fallback, and trace emission.