Guides

Nimbly Agent and the agent framework

An integrated assistant and framework for custom agents, conversations, tools and scheduled work.

Nimbly includes Nimbly Agent, an assistant that understands the framework and the current site, and an agent framework for project-specific agents. These are application capabilities: agents can participate in conversations and run defined workflows through the same platform as the rest of your system.

Nimbly Agent

The built-in agent helps authorized users find information, navigate the application and work with content. Its tools can read site resources and documentation, and create, update or delete records subject to the requesting user's rights.

Site context can be added in ext/agents/nimbly/project.md. This extends the built-in instructions while allowing framework updates to continue supplying the underlying agent definition.

Make it available to users

The built-in assistant requires the model provider configuration named in its definition, currently OPENAI_API_KEY in the runtime .env. Keep this credential outside tracked files.

The chat and the agent must be enabled in Site settings, and the user's role must grant chat-nimbly. A chat agent becomes available when its required environment settings, site switches and role permission are all present. The core HTML layout includes the team chat control for eligible signed-in users.

These access conditions are separate from the permissions for data operations. Giving a user access to chat does not grant permission to edit a resource.

Define a specialist agent

A project agent lives under ext/agents/<agent-id>/. Its agent.json defines its identity, instructions, tools, execution limits and pipelines. The built-in definition at core/modules/agent/agents/nimbly/agent.json is an implementation reference for a chat agent.

  • A chat_pipeline makes an agent available to the team chat.
  • A pipeline defines queued, scheduled or event-driven work.
  • Project connectors in ext/lib/agent-connector-<id>.php provide the integration behavior used by tools and pipeline steps.

A project definition with the same identity overrides the core definition. Add site context when that is enough; replace the definition when its behavior must differ.

Tools, execution and authorization

Agents use declared tools and connectors. Governed actions have an authorization step before execution. The Nimbly Agent's content tools act with the requesting user's rights. A custom agent must define the authorization appropriate to its actual operations rather than assuming conversation access grants executable capability.

The framework records runs, steps, events and actions, supporting inspection of what ran and its result. Queued and scheduled execution use the existing job and scheduling foundations. The project defines its domain logic, tools, schedules and operating limits.

For example, an events system can add a programme assistant or a scheduled workflow that prepares an event digest. The project implements the relevant tools, permissions and delivery behavior.

View this page as Markdown