Agent Persistence

[joshmeek]

Summary

This draft PR adds the foundation for being able to manage agents in the backend API. The idea here is that users will be able to create an Agent and then that agent will have a configuration on it where every time that user wants to use it they can spin up an AgentInstance with that configuration. Note: agent instances can still be spun up without setting a configuration and they will be persisted. The concept of prefect Agents doesn't really change and this separation of Agent / Instance is more for backend management.

Scenario:

• User enters UI and clicks "New Agent" on the agent management page
• User enters any agent configuration they want and that agent is created
• A command such as prefect agent start --agent-id XXXX is displayed that can be used to start an instance of that agent any time it is desired
• User starts an instance of that agent and all flow runs that are submitted by that agent are marked by which agent instance submitted it
• Now a more full agent experience is unlocked where visibility into the agent processes is exposed
• In the case where a user wants to change their agent configuration on the fly they can update it (e.g. via UI) and the agent instance(s) will auto pull the updated configuration
• This will also help identify distressed agent instances

This is meant to be used in collaboration with the agent_persistence branch in core. UI side to follow soon!

Opening as a draft PR to get comments and feedback on a few questions I have as well as things like the data models.

Changes

Two new tables are added to the DB agent which manages the configuration and agent_instance which manages things like name, labels, core_version, etc. (standard agent configuration kwargs). This also adds a new field to the flow run table agent_instance that is updated by the id of an agent instance when the flow run transitions into a submitted state. Some subsequent mutations are also implemented.

Open questions:

• Currently the agent_instance table tracks a last_query_time that is updated on every call to retrieve runs. Do we want this?
• Should the agent table expose the configuration name as config (current), settings, metadata, etc.
• Should the agent table have a name field? I can see a scenario of wanting to create an agent w/ a name.

Importance

Adding the ability to track/manage agents will open the doors to a better experience and provide more detailed information on what is happening across the platform. This also lays the foundation for future agent command patterns because we will be able to direct commands to specific agents/instances.

Checklist

This PR:

• adds new tests (if appropriate)
• adds a change file in the changes/ directory (if appropriate)

I don't expect tests to pass yet.

[codecov-commenter]

Codecov Report

Merging #58 into master will decrease coverage by 1.08%.
The diff coverage is 64.00%.

[cicdw]

Let's also replace all instances of models.Agent with prefect.api.models.Agent to ensure Cloud compatibility

[joshmeek]

Let's also replace all instances of models.Agent with prefect.api.models.Agent to ensure Cloud compatibility

@cicdw What do you mean? The Agent model is in prefect_server.models

[cicdw]

@joshmeek as an example, if we re-use the delete_agent route in Cloud, we want to make sure that models.Agent().delete() uses the Cloud model and not the Server model. Analogously to the prefect.api calls, we use prefect.api.models.Agent to ensure that the correct model is used in each call.

[jlowin]

🚀

[cicdw]

Awesome work @joshmeek ! Thanks for your patience through this extended review process