AI assistants & task agents

Define the output contract

The framework’s checked one-shot example uses named category and urgency enums with a Zod result schema. This selected schema excerpt depends on those enums, declared in the same example.

const TicketTriageSchema = z.object({
  category: z.enum(TicketCategory)
    .describe('The single best-fitting category for the ticket.'),
  urgency: z.enum(TicketUrgency)
    .describe(`How quickly a human must respond. "${TicketUrgency.HIGH}" only for outages, data loss, or billing failures.`),
  summary: z.string().max(200)
    .describe('One-sentence neutral summary of what the customer is asking for.'),
});

The corresponding agent declares GENERATE_STRUCTURED, an enabled provider and modelApplicability: LLM_Model_Applicability.STRUCTURED_AUTHORING. It also supplies the matching operation schemas, access configuration and durable prompt. Register it in the backend module’s flowsActors.agents contribution so its reference is resolvable.

The schema above is part of an illustrative framework example, not a claim that a support-triage product is delivered automatically.

Build the invocation and validate the answer

This selected method body follows that checked example. Its registered agent reference, schemas and injected AgentsBackendService are defined alongside it. The generic invocation and operation types come from the public model packages.

const invocation: FlowsActors_Agent_Invocation<
  typeof LLMProvider_GenerateStructuredInputSchema,
  typeof LLMProvider_GenerateStructuredOutputSchema,
  typeof LLMProvider_OperationContext_BaseSchema
> = {
  agentRef: TICKET_TRIAGE_AGENT_REF,
  initiator: {},
  invocationContext: [],
  input: {
    prompt: `Triage this support ticket:

${ticketBody}`,
    schema: TicketTriageSchema,
  },
  output: { object: {} },
  executionContext: { callTimestamp: new Date().toISOString() },
  artifactBindings: [],
};

const result = await this.agentsService.invokeAgent(invocation);
return TicketTriageSchema.parse((result.output as { object: unknown }).object);

result.output is wrapped by operation: structured generation returns an object, text generation returns text. The empty output is a seed for the invocation envelope, not a fallback classification.

Keep invocation and action distinct

One-shot generation does not execute declared function tools. Supply the required input from backend code. If the application then writes a record, calls another service or sends a notification, that effect needs its own permission and business contract.

Verify schema rejection as well as a useful answer. Do not replace a failed provider call with a fabricated successful business result.

Give the assistant a narrow action contract

This adapted Wonder Todos tool configuration keeps reads available and makes the title update subject to approval. The public tool factories are imported from @wildo-ai/saas-backend-lib; resource enums are application-owned.

const functionTools = [
  resourceReadTool(TasksManager_ResourceType.TODOS),
  resourceWriteTool(TasksManager_ResourceType.TODOS, CoreResourceOperation.UPDATE, {
    requiresHumanApproval: true,
    inputSchema: z.object({
      id: z.string().min(1)
        .describe('Resolve the todo identifier with the read tool.'),
      title: z.string().min(1).max(200)
        .describe('The new title requested by the person.'),
    }),
  }),
];

Register this array as the backend module’s flowsActors.functionTools and select the same function references on the CHAT agent. The actor system references that agent through its agentic actor. A reference that names an unregistered tool does not implement the action.

Place the registered system in the application

Wonder Todos declares this selected view entry. Surrounding view registries and imports are omitted.

{
  ref: 'todo-assistant-view',
  scope: FrontendView_ScopeMode.APPLICATION,
  isAddressable: true,
  operationLike: CoreResourceOperation.READ,
  primaryScope: ResourcePrimaryScope.ORGANIZATIONS,
  systemRef: 'todo-assistant',
  layoutPreset: 'Default',
},

The standard host connects streaming, history and configured approval controls to the registered system. systemRef identifies the system; it is not a prompt or an agent declaration.

Preserve the verified caller through tool execution

The local resource-tool path reconstructs context from the verified caller, authorizes the operation, applies its rate limit and dispatches its behavior. Approval does not replace those checks. Non-user principals do not gain an interactive approval flow merely because a tool requests one.

Outbound MCP tools are a separate integration path with destination and credential controls. They do not automatically inherit local resource-operation authorization. Test their access at the destination as well as the application’s tool selection.

Give a named interface an explicit selection

The framework’s A2A exposure guidance places named servers in ApplicationInitializationConfig.resourceServerInstances. This illustrative entry selects a registered support actor system. Import ResourceServerKind from @wildo-ai/saas-models.

resourceServerInstances: [{
  ref: 'concierge',
  kind: ResourceServerKind.A2A,
  displayName: 'Support concierge',
  description: 'An assistant for customer support questions.',
  actorSystemRefs: ['supportAssistant'],
}],

supportAssistant must identify an ACTOR system with an AGENTIC actor referencing the intended agent. This configuration selects the interface; it does not supply the agent implementation or an independently deployed process.

Inspect every exposed entry point

Named instances narrow their own selected actor systems and audience. The default /a2a interface remains additive; a named subset does not automatically remove the default exposure.

Frontend visibility is not an external access policy. Current exposure discovery selects eligible actor systems independently of whether a view is visible in the application. Review the configured interfaces and their audiences directly.

Match ownership to the caller

Exercise discovery and a real request with the intended client. Attempt access using another audience or principal and verify refusal. A generated agent card alone does not establish interoperability.

Do not turn a declared flow schedule into a claim of executed orchestration. Use the implemented conversation runtime, an autonomous-agent declaration or an application-authored caller, and verify the host that actually performs the work.