Implementing Agent Metadata Service

Signed-off-by: Future-Outlier <[email protected]>

docs/flyte_agents/implementing_agent_metadata_service.md

@@ -0,0 +1,43 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+---
+
+(implementing_agent_metadata_service)=
+# Implementing Agent Metadata Service
+
+## Why we need Agent Metadata Service?
+Before FlytePropeller sends a request to the agent server, it needs to know 4 things:
+
+1. What is the name of the agent?
+2. Which task category does the agent support?
+3. What version is the task category?
+4. Does the agent execute tasks synchronously or asynchronously?
+
+:::{note}
+1. An agent can support multiple task categories.
+2. We will use the combination of [task category][version] to identify the specific agent's deployment and know whether the task is synchronous or asynchronous in FlytePropeller.
+3. Task category is `task_type` in flytekit.
+:::
+
+Let's take BigQuery Agent as an example, it's name is `BigQuery Agent`, it supports `bigquery_query_job_task`, it's version is `0` by default, it executes task `asynchronously`.
+
+After FlytePropeller gets these metadata, it can send a request to the agent deployment using the correct gRPC method.
+
+
+## How to implement Agent Metadata Service?
+We need to do 2 things.
+
+1. Implement Agent Metadata Service.
+2. Add Agent Metadata Service to Agent Server.
+
+You can refer to [base_agent.py](https://github.com/flyteorg/flytekit/blob/master/flytekit/extend/backend/base_agent.py), [agent_service.py](https://github.com/flyteorg/flytekit/blob/master/flytekit/extend/backend/agent_service.py), and [serve.py](https://github.com/flyteorg/flytekit/blob/master/flytekit/clis/sdk_in_container/serve.py) to see how we implement Agent Metadata Service in flytekit's Agent Server.
+
+Those gRPC methods are generated by [flyteidl](https://github.com/flyteorg/flyte/blob/master/flyteidl/protos/flyteidl/service/agent.proto) and you can import them from [here](https://github.com/flyteorg/flyte/tree/master/flyteidl/gen).
+
+:::{note}
+You can search the keyword `metadata` to find implementations in those files.
+:::

docs/flyte_agents/index.md

@@ -41,6 +41,8 @@ For a list of agents you can use in your tasks and example usage for each, see t
   - Once you have tested an agent locally and want to use it in production, you must configure your Flyte deployment for the agent.
 * - {doc}`Deploying agents to the Flyte Sandbox <deploying_agents_to_the_flyte_sandbox>`
   - Once you have tested an agent locally and want to use it in production, you must want to test it in sandbox.
+* - {doc}`Implementing Agent Metadata Service <implementing_agent_metadata_service>`
+  - If you want to develop an agent server in a language other than Python, for example, rust or java, you must implement Agent Metadata Service in your Agent Server.
 ```
 
 ```{toctree}
@@ -52,4 +54,5 @@ testing_agents_locally
 testing_agents_in_the_development_environment
 enabling_agents_in_your_flyte_deployment
 deploying_agents_to_the_flyte_sandbox
+implementing_agent_metadata_service
 ```